toys 0.3.4 → 0.3.5
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.yardopts +2 -0
- data/CHANGELOG.md +6 -0
- data/README.md +97 -4
- data/builtins/do.rb +1 -1
- data/builtins/system.rb +9 -9
- data/docs/guide.md +59 -0
- data/docs/tutorial.md +11 -0
- data/lib/toys/standard_cli.rb +6 -2
- data/lib/toys/version.rb +1 -1
- metadata +12 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 20520c07615ed64145bf678f175e4e37835e69fe2b92c88f083b554c1902e969
|
4
|
+
data.tar.gz: b3e1efd5fc4e05a620d7834361e353840579c5b4c6c555f95da1f350d81737b0
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: cdd293b0870059e7ff90dfac63844046d435b4150cd32d15fa2e8b8bef39c975db6ba6df87af89bf84f17fa075a57ffd9b6499b7fbcd4206cc7a281701411aed
|
7
|
+
data.tar.gz: 3e75b09dc3e6df45113bbad6d2dfb9c40601eb35b743d3557455be8821ace82d5bc762c34c07c89d5faf043c9d10de08dd49227346578ab20c675bad8e57a6a3
|
data/.yardopts
CHANGED
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,11 @@
|
|
1
1
|
# Release History
|
2
2
|
|
3
|
+
### 0.3.5 / 2018-05-15
|
4
|
+
|
5
|
+
* CHANGED: Flag and arg blocks in the DSL have an interface more similar to the rest of the DSL.
|
6
|
+
* CHANGED: Renamed `execute do` to `script do`.
|
7
|
+
* IMPROVED: Help display uses `less` if available.
|
8
|
+
|
3
9
|
### 0.3.4 / 2018-05-14
|
4
10
|
|
5
11
|
* CHANGED: Renamed switch to flag
|
data/README.md
CHANGED
@@ -1,12 +1,105 @@
|
|
1
1
|
# Toys
|
2
2
|
|
3
|
-
Toys is a command line binary that lets you build your own suite of
|
4
|
-
line tools
|
5
|
-
|
3
|
+
Toys is a command line binary that lets you build your own personal suite of
|
4
|
+
command line tools using a Ruby DSL. Toys handles argument parsing, error
|
5
|
+
reporting, logging, help text, and many other details for you. Toys is designed
|
6
|
+
for software developers, IT specialists, and other power users who want to
|
7
|
+
write and organize scripts to automate their workflows.
|
8
|
+
|
9
|
+
I wrote Toys because I was accumulating dozens of ad hoc Ruby scripts that I
|
10
|
+
had written to automate everything from refreshing credentials, to displaying
|
11
|
+
git history in my favorite format, to running builds and tests of complex
|
12
|
+
multi-component projects. It was becoming difficult to remember which scripts
|
13
|
+
did what, and what arguments to pass, and I was repeating the same
|
14
|
+
OptionParser and common tool boilerplate each time I wrote a new one.
|
15
|
+
|
16
|
+
Toys is a powerful tool that makes it easy to write and organize your scripts.
|
17
|
+
You write your functionality, and Toys takes care of all the details expected
|
18
|
+
from a good command line tool.
|
19
|
+
|
20
|
+
You can also use the core functionality of Toys to create your own command line
|
21
|
+
binaries, by using the *toys-core* API, which is available as a separate gem.
|
22
|
+
For more info on using toys-core, see
|
23
|
+
[https://ruby-doc.info/gems/toys-core](https://ruby-doc.info/gems/toys-core).
|
6
24
|
|
7
25
|
## Quick Start
|
8
26
|
|
9
|
-
|
27
|
+
Here's a five-minute tutorial to get the feel of what Toys can do.
|
28
|
+
|
29
|
+
### Install toys
|
30
|
+
|
31
|
+
Install the **toys** gem using:
|
32
|
+
|
33
|
+
gem install toys
|
34
|
+
|
35
|
+
This installs the `toys` binary, along with some builtin tools and libraries.
|
36
|
+
You can run the binary immediately:
|
37
|
+
|
38
|
+
toys
|
39
|
+
|
40
|
+
This displays overall help for the Toys binary. If you have `less` installed,
|
41
|
+
Toys will use it to display the help screen. Press `q` to exit.
|
42
|
+
|
43
|
+
You may notice that the help text lists some tools that are preinstalled. Let's
|
44
|
+
run one of them:
|
45
|
+
|
46
|
+
toys system version
|
47
|
+
|
48
|
+
The "system version" tool displays the current version of the toys gem.
|
49
|
+
|
50
|
+
### Write your first tool
|
51
|
+
|
52
|
+
You can define tools by creating toys *config files*. Using your favorite
|
53
|
+
editor, create a new file called `.toys.rb` (note the leading period) in your
|
54
|
+
current directory. Copy the following into the file, and save it:
|
55
|
+
|
56
|
+
tool "greet" do
|
57
|
+
desc "My first tool!"
|
58
|
+
flag :whom, default: "world"
|
59
|
+
script do
|
60
|
+
puts "Hello, #{options[:whom]}!"
|
61
|
+
end
|
62
|
+
end
|
63
|
+
|
64
|
+
This defines a tool named "greet". Try running it:
|
65
|
+
|
66
|
+
toys greet
|
67
|
+
|
68
|
+
The tool also recognizes a flag on the command line. Try this:
|
69
|
+
|
70
|
+
toys greet --whom=ruby
|
71
|
+
|
72
|
+
Toys provides a rich set of features for defining command line arguments and
|
73
|
+
flags. It can also validate arguments. Try this:
|
74
|
+
|
75
|
+
toys greet --hello
|
76
|
+
|
77
|
+
Notice that Toys automatically generated a usage summary for your tool. It also
|
78
|
+
automatically generates a full help screen, which you can view using the
|
79
|
+
`--help` flag:
|
80
|
+
|
81
|
+
toys greet --help
|
82
|
+
|
83
|
+
### Next steps
|
84
|
+
|
85
|
+
You can add any number of additional tools to your `.toys.rb` file. Note also
|
86
|
+
that the tools you created in that file are available only in this directory
|
87
|
+
and its subdirectories; if you move outside the directory tree, they are no
|
88
|
+
longer present. You can use this to create tools scoped to particular
|
89
|
+
directories and projects.
|
90
|
+
|
91
|
+
Toys also lets you create hierarchies of tools. The "system version" tool you
|
92
|
+
tried earlier is an example. The "system" tool is treated as a namespace, and
|
93
|
+
various subtools, such as "version", are available under that namespace.
|
94
|
+
|
95
|
+
Toys provides a rich set of useful libraries for writing tools. It gives you a
|
96
|
+
logger and automatically provides flags to control verbosity of log output. It
|
97
|
+
includes the Highline library, which you can use to produce styled output,
|
98
|
+
console-based interfaces, and special effects. It also includes a library that
|
99
|
+
makes it easy to control subprocesses.
|
100
|
+
|
101
|
+
For a more detailed look at Toys, see the
|
102
|
+
{file:docs/tutorial.md Extended Tutorial} and {file:docs/guide.md User Guide}.
|
10
103
|
|
11
104
|
## Contributing
|
12
105
|
|
data/builtins/do.rb
CHANGED
data/builtins/system.rb
CHANGED
@@ -27,22 +27,22 @@
|
|
27
27
|
# POSSIBILITY OF SUCH DAMAGE.
|
28
28
|
;
|
29
29
|
|
30
|
-
desc "A
|
30
|
+
desc "A set of system commands for Toys"
|
31
31
|
|
32
|
-
long_desc "Contains tools that inspect, configure, and update
|
32
|
+
long_desc "Contains tools that inspect, configure, and update Toys itself."
|
33
33
|
|
34
34
|
tool "version" do
|
35
|
-
desc "Print current
|
35
|
+
desc "Print current Toys version."
|
36
36
|
|
37
|
-
|
37
|
+
script do
|
38
38
|
puts ::Toys::VERSION
|
39
39
|
end
|
40
40
|
end
|
41
41
|
|
42
42
|
tool "update" do
|
43
|
-
desc "Update
|
43
|
+
desc "Update Toys if a newer version is available."
|
44
44
|
|
45
|
-
long_desc "Checks rubygems for a newer version of
|
45
|
+
long_desc "Checks rubygems for a newer version of Toys. If one is available, downloads" \
|
46
46
|
" and installs it."
|
47
47
|
|
48
48
|
flag :yes, "-y", "--yes", desc: "Do not ask for interactive confirmation"
|
@@ -50,8 +50,8 @@ tool "update" do
|
|
50
50
|
use :exec
|
51
51
|
use :highline
|
52
52
|
|
53
|
-
|
54
|
-
logger.info "Checking rubygems for the latest
|
53
|
+
script do
|
54
|
+
logger.info "Checking rubygems for the latest Toys release..."
|
55
55
|
version_info = capture("gem query -q -r -e toys")
|
56
56
|
if version_info =~ /toys\s\((.+)\)/
|
57
57
|
latest_version = ::Gem::Version.new($1)
|
@@ -67,7 +67,7 @@ tool "update" do
|
|
67
67
|
logger.warn("Toys is already at the latest version: #{latest_version}")
|
68
68
|
end
|
69
69
|
else
|
70
|
-
logger.error("Could not get latest
|
70
|
+
logger.error("Could not get latest Toys version")
|
71
71
|
exit(1)
|
72
72
|
end
|
73
73
|
end
|
data/docs/guide.md
ADDED
@@ -0,0 +1,59 @@
|
|
1
|
+
# @title Toys User Guide
|
2
|
+
|
3
|
+
# Toys User Guide
|
4
|
+
|
5
|
+
Toys is a command line binary that lets you build your own personal suite of
|
6
|
+
command line tools using a Ruby DSL. Toys handles argument parsing, error
|
7
|
+
reporting, logging, help text, and many other details for you. Toys is designed
|
8
|
+
for software developers, IT specialists, and other power users who want to
|
9
|
+
write and organize scripts to automate their workflows.
|
10
|
+
|
11
|
+
This user's guide covers everything you need to know to use Toys effectively.
|
12
|
+
|
13
|
+
## Conceptual overview
|
14
|
+
|
15
|
+
Toys is a command line *framework*. It provides a binary called `toys` along
|
16
|
+
with basic functions such as argument parsing and online help. You provide the
|
17
|
+
actual behavior of the toys binary by writing *configuration files*.
|
18
|
+
|
19
|
+
Toys is a multi-command binary. You may define a collection of commands, called
|
20
|
+
*tools*, which can be invoked by passing the tool name as an argument to the
|
21
|
+
`toys` binary. Tools are arranged in a hierarchy; a tool may be a *namespace*
|
22
|
+
that has *subtools*.
|
23
|
+
|
24
|
+
Each tool defines the command line arguments, in the form of *flags* and
|
25
|
+
*positional arguments*, that it recognizes. Flags can optionally take *values*,
|
26
|
+
and positional arguments may be *required* or *optional*.
|
27
|
+
|
28
|
+
The configuration of a tool may define *descriptions*, for the tool itself, and
|
29
|
+
for each command line argument. These descriptions are displayed in the tool's
|
30
|
+
*online help* screen. Descriptions come in *long* and *short* forms, which
|
31
|
+
appear in different styles of help.
|
32
|
+
|
33
|
+
Toys searches for configuration in specifically-named *configuration files* and
|
34
|
+
*configuration directories*. It searches for these in the current directory,
|
35
|
+
and in a *configuration search path*.
|
36
|
+
|
37
|
+
Toys provides various features to help you write tools. This includes providing
|
38
|
+
a *logger* for each tool, *helper modules* that provide common functions a tool
|
39
|
+
can call, and *templates* which are prefabricated tools you can add to your
|
40
|
+
configuration.
|
41
|
+
|
42
|
+
Finally, Toys provides certain *built-in behavior*, including automatically
|
43
|
+
providing flags to display help screens and set verbosity. It also includes a
|
44
|
+
built-in namespace of *system tools* that let you inspect and configure the
|
45
|
+
Toys system.
|
46
|
+
|
47
|
+
## The Toys Command Line
|
48
|
+
|
49
|
+
## Config Syntax
|
50
|
+
|
51
|
+
## Config Search Path
|
52
|
+
|
53
|
+
## Defining Helpers
|
54
|
+
|
55
|
+
## Defining Templates
|
56
|
+
|
57
|
+
## Built-in Flags and Behavior
|
58
|
+
|
59
|
+
## Embedding Toys
|
data/docs/tutorial.md
ADDED
@@ -0,0 +1,11 @@
|
|
1
|
+
# @title Toys Tutorial
|
2
|
+
|
3
|
+
# Toys Tutorial
|
4
|
+
|
5
|
+
Toys is a command line binary that lets you build your own personal suite of
|
6
|
+
command line tools using a Ruby DSL. Toys handles argument parsing, error
|
7
|
+
reporting, logging, help text, and many other details for you. Toys is designed
|
8
|
+
for software developers, IT specialists, and other power users who want to
|
9
|
+
write and organize scripts to automate their workflows.
|
10
|
+
|
11
|
+
(To be written)
|
data/lib/toys/standard_cli.rb
CHANGED
@@ -158,7 +158,9 @@ module Toys
|
|
158
158
|
usage_flags: true,
|
159
159
|
recursive_flags: true,
|
160
160
|
search_flags: true,
|
161
|
-
|
161
|
+
default_recursive: true,
|
162
|
+
allow_root_args: true,
|
163
|
+
use_less: true
|
162
164
|
],
|
163
165
|
[
|
164
166
|
:show_version,
|
@@ -171,7 +173,9 @@ module Toys
|
|
171
173
|
:show_help,
|
172
174
|
fallback_execution: true,
|
173
175
|
recursive_flags: true,
|
174
|
-
search_flags: true
|
176
|
+
search_flags: true,
|
177
|
+
default_recursive: true,
|
178
|
+
use_less: true
|
175
179
|
],
|
176
180
|
[
|
177
181
|
:add_verbosity_flags
|
data/lib/toys/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: toys
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.3.
|
4
|
+
version: 0.3.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-05-
|
11
|
+
date: 2018-05-15 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: toys-core
|
@@ -16,14 +16,14 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - '='
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: 0.3.
|
19
|
+
version: 0.3.5
|
20
20
|
type: :runtime
|
21
21
|
prerelease: false
|
22
22
|
version_requirements: !ruby/object:Gem::Requirement
|
23
23
|
requirements:
|
24
24
|
- - '='
|
25
25
|
- !ruby/object:Gem::Version
|
26
|
-
version: 0.3.
|
26
|
+
version: 0.3.5
|
27
27
|
- !ruby/object:Gem::Dependency
|
28
28
|
name: minitest
|
29
29
|
requirement: !ruby/object:Gem::Requirement
|
@@ -94,7 +94,11 @@ dependencies:
|
|
94
94
|
- - "~>"
|
95
95
|
- !ruby/object:Gem::Version
|
96
96
|
version: '0.9'
|
97
|
-
description:
|
97
|
+
description: Toys is a command line binary that lets you build your own personal suite
|
98
|
+
of command line tools using a Ruby DSL. Toys handles argument parsing, error reporting,
|
99
|
+
logging, help text, and many other details for you. It is designed for software
|
100
|
+
developers, IT specialists, and other power users who want to write and organize
|
101
|
+
scripts to automate their workflows.
|
98
102
|
email:
|
99
103
|
- dazuma@gmail.com
|
100
104
|
executables:
|
@@ -109,6 +113,8 @@ files:
|
|
109
113
|
- bin/toys
|
110
114
|
- builtins/do.rb
|
111
115
|
- builtins/system.rb
|
116
|
+
- docs/guide.md
|
117
|
+
- docs/tutorial.md
|
112
118
|
- lib/toys.rb
|
113
119
|
- lib/toys/standard_cli.rb
|
114
120
|
- lib/toys/version.rb
|
@@ -135,5 +141,5 @@ rubyforge_project:
|
|
135
141
|
rubygems_version: 2.7.6
|
136
142
|
signing_key:
|
137
143
|
specification_version: 4
|
138
|
-
summary:
|
144
|
+
summary: Framework for creating personal command line tools
|
139
145
|
test_files: []
|