toys 0.4.5 → 0.5.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.yardopts +1 -0
- data/CHANGELOG.md +11 -0
- data/docs/guide.md +239 -24
- data/lib/toys.rb +7 -4
- data/lib/toys/standard_cli.rb +33 -3
- data/lib/toys/templates/rake.rb +123 -0
- data/lib/toys/version.rb +1 -1
- metadata +42 -9
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 516ab9d472491bb7250ac10e033024dd2e621908836d8e7ccce46d563418d3d3
|
4
|
+
data.tar.gz: 706e194857b09e1f24f2a360d03ba42259b1782284c80f56299bef3d5dc991b4
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 21ea81146849ffa1549803556ec237af812223b7d3e88ae4f36115ac1ee45ce8795bedbc3b6cbf5168322d557cb85397e89c51195bb8385172ab1bc61b47b24f
|
7
|
+
data.tar.gz: 0c5ec538c871002c01261cfe662ba732f164fb977ed7906460608517f86c0bc16319ba7da3f7e5294ac8aab7e786a5ab0126dbfe7c5ff50d4815ce3514514c8e
|
data/.yardopts
CHANGED
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,16 @@
|
|
1
1
|
# Release History
|
2
2
|
|
3
|
+
### 0.5.0 / 2018-10-07
|
4
|
+
|
5
|
+
* ADDED: Period and colon are recognized as tool path delimiters.
|
6
|
+
* ADDED: New rake template that supports loading rake tasks as tools.
|
7
|
+
* ADDED: Files named ".preload.rb" and files in a ".preload" directory are loaded before tools are defined.
|
8
|
+
* ADDED: Directories named ".data" can contain data files accessible from tools.
|
9
|
+
* ADDED: Passing "--tools" displays just the list of subtools of a tool
|
10
|
+
* IMPROVED: The tool directive can now take an array as the tool name.
|
11
|
+
* IMPROVED: The tool directive can now take an `if_defined` argument.
|
12
|
+
* FIXED: Template instantiation was failing if the hosting tool was priority-masked.
|
13
|
+
|
3
14
|
### 0.4.5 / 2018-08-05
|
4
15
|
|
5
16
|
* CHANGED: Dropped preload file feature
|
data/docs/guide.md
CHANGED
@@ -79,6 +79,13 @@ words. Tools are arranged hierarchically. In this case, `system` is a
|
|
79
79
|
**namespace** for tools related to the Toys system, and `version` is one of its
|
80
80
|
**subtools**. It prints the current Toys version.
|
81
81
|
|
82
|
+
The words in a tool name can be delimited with spaces as shown above, or
|
83
|
+
alternately periods or colons. The following commands also invoke the tool
|
84
|
+
`system version`:
|
85
|
+
|
86
|
+
toys system.version
|
87
|
+
toys system:version
|
88
|
+
|
82
89
|
In the following command:
|
83
90
|
|
84
91
|
|TOOL| |ARG|
|
@@ -433,8 +440,8 @@ an example:
|
|
433
440
|
long_desc: ["Long descriptions may have multiple lines.",
|
434
441
|
"This is the second line."]
|
435
442
|
|
436
|
-
See the [above section on Descriptions](#
|
437
|
-
how descriptions are rendered and word wrapped.
|
443
|
+
See the [above section on Descriptions](#Tool_Descriptions) for more
|
444
|
+
information on how descriptions are rendered and word wrapped.
|
438
445
|
|
439
446
|
Because long descriptions may be unwieldly to write as a hash argument in this
|
440
447
|
way, Toys provides an alternate syntax for defining arguments using a block.
|
@@ -477,7 +484,7 @@ and
|
|
477
484
|
[OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
|
478
485
|
|
479
486
|
You may also create **custom acceptors**. See the
|
480
|
-
[section below on Custom Acceptors](#
|
487
|
+
[section below on Custom Acceptors](#Custom_Acceptors) for more information.
|
481
488
|
|
482
489
|
### Flags
|
483
490
|
|
@@ -570,7 +577,7 @@ and
|
|
570
577
|
[OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
|
571
578
|
|
572
579
|
You may also create **custom acceptors**. See the
|
573
|
-
[section below on Custom Acceptors](#
|
580
|
+
[section below on Custom Acceptors](#Custom_Acceptors) for more information.
|
574
581
|
|
575
582
|
#### Defaults and Handlers
|
576
583
|
|
@@ -619,7 +626,7 @@ like this:
|
|
619
626
|
Note that both flags affect the same option value, `VERBOSITY`. The first
|
620
627
|
increments it each time it appears, and the second decrements it. A tool can
|
621
628
|
query this option and get an integer telling the requested verbosity level, as
|
622
|
-
you will see [below](#
|
629
|
+
you will see [below](#Logging_and_Verbosity).
|
623
630
|
|
624
631
|
#### Descriptions and the Flags DSL
|
625
632
|
|
@@ -633,7 +640,7 @@ directive. The `desc:` argument takes a single string description, while the
|
|
633
640
|
long_desc: ["Long descriptions may have multiple lines.",
|
634
641
|
"This is the second line."]
|
635
642
|
|
636
|
-
See the [above section on Descriptions](#
|
643
|
+
See the [above section on Descriptions](#Tool_Descriptions) for more information on
|
637
644
|
how descriptions are rendered and word wrapped.
|
638
645
|
|
639
646
|
Because long descriptions may be unwieldly to write as a hash argument in this
|
@@ -659,7 +666,7 @@ your tools.
|
|
659
666
|
|
660
667
|
Note: If you do not define the `run` method for a tool, Toys provides a default
|
661
668
|
implementation that displays the tool's help screen. This is typically used for
|
662
|
-
namespaces, as we shall see [below](#
|
669
|
+
namespaces, as we shall see [below](#Namespaces_and_Subtools). Most tools,
|
663
670
|
however, should define `run`.
|
664
671
|
|
665
672
|
Let's revisit the "greet" example we covered earlier.
|
@@ -824,7 +831,7 @@ than two or three levels of hierarchy can be confusing to use.
|
|
824
831
|
## Understanding Toys Files
|
825
832
|
|
826
833
|
Toys commands are defined in Toys files. We covered the basic syntax for these
|
827
|
-
files in the [above section on defining tools](#
|
834
|
+
files in the [above section on defining tools](#Defining_Tools). In this
|
828
835
|
section, we will take a deeper look at what you can do with Toys files.
|
829
836
|
|
830
837
|
### Toys Directories
|
@@ -929,7 +936,7 @@ in the separate file `.toys/test/unit.rb`.
|
|
929
936
|
Toys also loads index files first before other files in the directory. This
|
930
937
|
means they are convenient places to define shared code that can be used by all
|
931
938
|
the subtools defined in that directory, as we shall see later in the
|
932
|
-
[section on sharing code](#
|
939
|
+
[section on sharing code](#Sharing_Code).
|
933
940
|
|
934
941
|
### The Toys Search Path
|
935
942
|
|
@@ -1047,7 +1054,7 @@ or the
|
|
1047
1054
|
[Toys::Tool#verbosity method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:verbosity).
|
1048
1055
|
The verbosity is set to 0 by default. This corresponds to a logger level of
|
1049
1056
|
`WARN`. That is, warnings, errors, and fatals are displayed, while infos and
|
1050
|
-
debugs are not. However, [as we saw earlier](#
|
1057
|
+
debugs are not. However, [as we saw earlier](#Standard_Flags), most tools
|
1051
1058
|
automatically respond to the `--verbose` and `--quiet` flags, (or `-v` and
|
1052
1059
|
`-q`), which increment and decrement the verbosity value, respectively. If you
|
1053
1060
|
run a tool with `-v`, the verbosity is incremented to 1, and the logger level
|
@@ -1076,7 +1083,7 @@ execute, and return a process status object (i.e. 0 for success, and nonzero
|
|
1076
1083
|
for error). Make sure you handle the exit status. For example, in most cases,
|
1077
1084
|
you should probably exit if the tool you are calling returns a nonzero code.
|
1078
1085
|
|
1079
|
-
You may also use the `exec` mixin [described below](#
|
1086
|
+
You may also use the `exec` mixin [described below](#Executing_Subprocesses) to
|
1080
1087
|
run a tool in a separate process. This is particularly useful if you need to
|
1081
1088
|
capture or manipulate that tool's input or output.
|
1082
1089
|
|
@@ -1084,7 +1091,7 @@ capture or manipulate that tool's input or output.
|
|
1084
1091
|
|
1085
1092
|
The methods of [Toys::Tool](https://www.rubydoc.info/gems/toys-core/Toys/Tool)
|
1086
1093
|
are not the only methods available for your tool to call. We
|
1087
|
-
[saw earlier](#
|
1094
|
+
[saw earlier](#Tool_Execution_Basics) that a tool can define additional methods
|
1088
1095
|
that you can use as helpers.
|
1089
1096
|
|
1090
1097
|
You can also include **mixins**, which are modules that bring in a whole set of
|
@@ -1109,7 +1116,7 @@ We will look at a few examples of the use of these mixins below. Built-in
|
|
1109
1116
|
mixins have names that are symbols.
|
1110
1117
|
|
1111
1118
|
You can also define your own mixins, as we will see in the
|
1112
|
-
[
|
1119
|
+
[upcoming section on defining mixins](#Defining-Mixins).
|
1113
1120
|
|
1114
1121
|
### Executing Subprocesses
|
1115
1122
|
|
@@ -1167,7 +1174,7 @@ more information, see the
|
|
1167
1174
|
|
1168
1175
|
You may also use other third-party gems such as
|
1169
1176
|
[tty](https://github.com/piotrmurach/tty). The section below on
|
1170
|
-
[useful gems](#
|
1177
|
+
[useful gems](#Useful_Gems) provides some examples.
|
1171
1178
|
|
1172
1179
|
## Sharing Code
|
1173
1180
|
|
@@ -1180,7 +1187,7 @@ classes, and constants, that you might define in your tools.
|
|
1180
1187
|
|
1181
1188
|
### Defining Mixins
|
1182
1189
|
|
1183
|
-
We [saw earlier](#
|
1190
|
+
We [saw earlier](#Helper_Methods_and_Mixins) that you can mix a module (with
|
1184
1191
|
all its methods) into your tool using the `include` directive. You can specify
|
1185
1192
|
a module itself, or the name of a built-in mixin such as `:exec` or
|
1186
1193
|
`:terminal`. But you can also define your own mixin using the `mixin`
|
@@ -1195,7 +1202,7 @@ includes the mixin, in the same way that you can include a Ruby module.
|
|
1195
1202
|
|
1196
1203
|
(Note that, unlike full modules, mixins allow only methods to be shared. Mixins
|
1197
1204
|
do not support constants. See the next section on
|
1198
|
-
[using constants](#
|
1205
|
+
[using constants](#Using_Constants) to learn how Toys handles constants.)
|
1199
1206
|
|
1200
1207
|
Here's an example. Suppose you had common setup code that you wanted to share
|
1201
1208
|
among your testing tools.
|
@@ -1402,7 +1409,7 @@ development, including templates that generate build, test, and documentation
|
|
1402
1409
|
tools. The `:minitest` template illustrated above is one of these built-in
|
1403
1410
|
templates. Like built-in mixins, built-in template names are always symbols.
|
1404
1411
|
You can read more about them in the next section on using
|
1405
|
-
[Toys as a Rake replacement](#
|
1412
|
+
[Toys as a Rake replacement](#Toys_as_a_Rake_Replacement).
|
1406
1413
|
|
1407
1414
|
You may also write your own templates. Here's how...
|
1408
1415
|
|
@@ -1509,6 +1516,152 @@ following in their Toys file:
|
|
1509
1516
|
require "my_analysis"
|
1510
1517
|
expand MyAnalysis::ToysTemplate
|
1511
1518
|
|
1519
|
+
### Preloading Ruby Files
|
1520
|
+
|
1521
|
+
For more complicated tools, you might want to write normal Ruby modules and
|
1522
|
+
classes as helpers. Toys provides a way to write Ruby code outside of its DSL
|
1523
|
+
and incorporate it into your tool definitions, using "preloaded" files.
|
1524
|
+
|
1525
|
+
A preloaded file is loaded using the standard Ruby `require` mechanism, before
|
1526
|
+
tools are defined. You can use such files to define Ruby classes, modules, and
|
1527
|
+
other code that may be used and shared by your tools.
|
1528
|
+
|
1529
|
+
To use preloaded files, you must define your tools inside a
|
1530
|
+
[Toys directory](#Toys_Directories). Before any tools inside a directory are
|
1531
|
+
loaded, any file named `.preload.rb` in the directory is automatically
|
1532
|
+
required. Additionally, any Ruby files inside a subdirectory called `.preload`
|
1533
|
+
are also automatically required.
|
1534
|
+
|
1535
|
+
For example, take the following directory structure:
|
1536
|
+
|
1537
|
+
(current directory)
|
1538
|
+
|
|
1539
|
+
+- .toys/
|
1540
|
+
|
|
1541
|
+
+- .preload.rb <-- required first
|
1542
|
+
|
|
1543
|
+
+- greet.rb <-- defines "greet" (and subtools)
|
1544
|
+
|
|
1545
|
+
+- test/
|
1546
|
+
|
|
1547
|
+
+- .preload/
|
1548
|
+
| |
|
1549
|
+
| +- my_classes.rb <-- required before unit.rb
|
1550
|
+
| |
|
1551
|
+
| +- my_modules.rb <-- also required before unit.rb
|
1552
|
+
|
|
1553
|
+
+- unit.rb <-- defines "test unit" (and its subtools)
|
1554
|
+
|
1555
|
+
Toys will execute
|
1556
|
+
|
1557
|
+
require ".toys/.preload.rb"
|
1558
|
+
|
1559
|
+
first before loading any of the tools in the `.toys` directory (or any of its
|
1560
|
+
subdirectories). Thus, you can define classes used by both the `greet` and the
|
1561
|
+
`test unit` tool in this file.
|
1562
|
+
|
1563
|
+
Furthermore, Toys will also execute
|
1564
|
+
|
1565
|
+
require ".toys/test/.preload/my_classes.rb"
|
1566
|
+
require ".toys/test/.preload/my_modules.rb"
|
1567
|
+
|
1568
|
+
first before loading any of the tools in the `test` subdirectory. Thus, any
|
1569
|
+
additional classes needed by `test unit` can be defined in these files.
|
1570
|
+
|
1571
|
+
Either a single `.preload.rb` file or a `.preload` directory, or both, may be
|
1572
|
+
used. If both are present, the `.preload.rb` file is loaded first before the
|
1573
|
+
`.preload` directory contents.
|
1574
|
+
|
1575
|
+
### Data Files
|
1576
|
+
|
1577
|
+
If your tools require images, archives, keys, or other such static data, Toys
|
1578
|
+
provides a convenient place to put data files that can be looked up by tools
|
1579
|
+
either during definition or runtime.
|
1580
|
+
|
1581
|
+
To use data files, you must define your tools inside a
|
1582
|
+
[Toys directory](#Toys_Directories). Within the Toys directory, create a
|
1583
|
+
directory named `.data` and copy your data files there. You may "find" a data
|
1584
|
+
file using the `find_data` directive in a Toys file, or by calling the
|
1585
|
+
`find_data` method in a tool. The `find_data` mechanism takes a relative path
|
1586
|
+
to a file, locates a matching file (or directory) among the data files, and
|
1587
|
+
returns the full path to that file system object. You may then read the file
|
1588
|
+
or perform any other operation on it.
|
1589
|
+
|
1590
|
+
For example, take the following directory structure:
|
1591
|
+
|
1592
|
+
(current directory)
|
1593
|
+
|
|
1594
|
+
+- .toys/
|
1595
|
+
|
|
1596
|
+
+- .data
|
1597
|
+
| |
|
1598
|
+
| +- greeting.txt
|
1599
|
+
| |
|
1600
|
+
| +- desc/
|
1601
|
+
| |
|
1602
|
+
| +- short.txt
|
1603
|
+
|
|
1604
|
+
+- greet.rb <-- defines "greet" (and subtools)
|
1605
|
+
|
1606
|
+
The data files in `.toys/.data` are available to any tool in the `.toys`
|
1607
|
+
directory or any of its subdirectories. For example, suppose we want our
|
1608
|
+
"greet" tool to use the contents of `greeting.txt`. We can call `find_data` to
|
1609
|
+
read those contents when the tool is executed:
|
1610
|
+
|
1611
|
+
# greet.rb
|
1612
|
+
desc "Print a friendly greeting."
|
1613
|
+
optional_arg :whom, default: "world", desc: "Whom to greet."
|
1614
|
+
def run
|
1615
|
+
greeting = IO.read(find_data("greeting.txt")).strip
|
1616
|
+
puts "#{greeting}, #{whom}!"
|
1617
|
+
end
|
1618
|
+
|
1619
|
+
You can include directories in the argument to `find_data`. For example, here
|
1620
|
+
is how to use the `find_data` directive to read the short description from the
|
1621
|
+
file "desc/short.txt":
|
1622
|
+
|
1623
|
+
# greet.rb
|
1624
|
+
desc IO.read(find_data("desc/short.txt")).strip
|
1625
|
+
optional_arg :whom, default: "world", desc: "Whom to greet."
|
1626
|
+
def run
|
1627
|
+
greeting = IO.read(find_data("greeting.txt")).strip
|
1628
|
+
puts "#{greeting}, #{whom}!"
|
1629
|
+
end
|
1630
|
+
|
1631
|
+
The `find_data` mechanism will return the "closest" file or directory found.
|
1632
|
+
In the example below, there is a `desc/short.txt` file in the `.data` directory
|
1633
|
+
at the top level, but there is also a `desc/short.txt` file in the `.data`
|
1634
|
+
directory under `test`. Tools under the `test` directory will find the more
|
1635
|
+
specific data file, while other tools will find the more general file.
|
1636
|
+
|
1637
|
+
(current directory)
|
1638
|
+
|
|
1639
|
+
+- .toys/
|
1640
|
+
|
|
1641
|
+
+- .data
|
1642
|
+
| |
|
1643
|
+
| +- greeting.txt
|
1644
|
+
| |
|
1645
|
+
| +- desc/
|
1646
|
+
| |
|
1647
|
+
| +- short.txt <-- default description for all tools
|
1648
|
+
|
|
1649
|
+
+- greet.rb <-- defines "greet" (and subtools)
|
1650
|
+
|
|
1651
|
+
+- test/
|
1652
|
+
|
|
1653
|
+
+- .data
|
1654
|
+
| |
|
1655
|
+
| +- desc/
|
1656
|
+
| |
|
1657
|
+
| +- short.txt <-- override description for test tools
|
1658
|
+
|
|
1659
|
+
+- unit.rb <-- defines "test unit" (and its subtools)
|
1660
|
+
|
1661
|
+
If, however, you find `greeting.txt` from a tool under `test`, it will still
|
1662
|
+
find the more general `.toys/.data/greeting.txt` file because there is no
|
1663
|
+
overriding file under `.toys/test/.data`.
|
1664
|
+
|
1512
1665
|
## Using Third-Party Gems
|
1513
1666
|
|
1514
1667
|
The Ruby community has developed many resources for building command line
|
@@ -1662,7 +1815,7 @@ directory. Rake is also commonly used for this purpose: you can write a
|
|
1662
1815
|
"Rakefile" that defines rake tasks scoped to a directory. In many cases, Toys
|
1663
1816
|
can be used as a replacement for Rake. Indeed, the Toys repository itself
|
1664
1817
|
contains a `.toys.rb` file that defines tools for running tests, builds, and so
|
1665
|
-
forth, instead of a Rakefile
|
1818
|
+
forth, instead of a Rakefile.
|
1666
1819
|
|
1667
1820
|
This section will explore the differences between Toys and Rake, and describe
|
1668
1821
|
how to use Toys for some of the things traditionally done with Rake.
|
@@ -1709,15 +1862,77 @@ your build tasks. Rake will continue to be your friend in those cases. However,
|
|
1709
1862
|
for high level tasks such as "run my tests", "build my YARD documentation", or
|
1710
1863
|
"release my gem", you may find Toys easier to use.
|
1711
1864
|
|
1865
|
+
### Using Toys to Invoke Rake Tasks
|
1866
|
+
|
1867
|
+
If you've already written a Rakefile for your project, Toys provides a
|
1868
|
+
convenient way to invoke your existing Rake tasks using Toys. The built-in
|
1869
|
+
`:rake` template reads a Rakefile and automatically generates corresponding
|
1870
|
+
tools.
|
1871
|
+
|
1872
|
+
In the same directory as your Rakefile, create a `.toys.rb` file with the
|
1873
|
+
following contents:
|
1874
|
+
|
1875
|
+
# In .toys.rb
|
1876
|
+
expand :rake
|
1877
|
+
|
1878
|
+
Now within that directory, if you had a task called `test`, you can invoke it
|
1879
|
+
with:
|
1880
|
+
|
1881
|
+
toys test
|
1882
|
+
|
1883
|
+
Similarly, a task named `test:integration` can be invoekd with either of the
|
1884
|
+
following:
|
1885
|
+
|
1886
|
+
toys test integration
|
1887
|
+
toys test:integration
|
1888
|
+
|
1889
|
+
Rake tasks with arguments are mapped to tool arguments, making it easier to
|
1890
|
+
invoke those tasks using Toys. For example, consider a Rake task with two
|
1891
|
+
arguments, defined as follows:
|
1892
|
+
|
1893
|
+
# In Rakefile
|
1894
|
+
task :my_task, [:first, :second] do |task, args|
|
1895
|
+
do_something_with args[:first]
|
1896
|
+
do_something_else_with args[:second]
|
1897
|
+
end
|
1898
|
+
|
1899
|
+
would have to be invoked as follows using rake:
|
1900
|
+
|
1901
|
+
rake my_task[value1,value2]
|
1902
|
+
|
1903
|
+
You may even need to escape the brackets if you are using a shell that treats
|
1904
|
+
them specially. Toys will let you pass them as normal command line arguments:
|
1905
|
+
|
1906
|
+
toys my_task value1 value2
|
1907
|
+
|
1908
|
+
The `:rake` template provides several options. If your Rakefile is named
|
1909
|
+
something other than `Rakefile` or isn't in the current directory, you can
|
1910
|
+
pass an explicit path to it when expanding the template:
|
1911
|
+
|
1912
|
+
# In .toys.rb
|
1913
|
+
expand :rake, rakefile_path: "path/to/my_rakefile"
|
1914
|
+
|
1915
|
+
You may also choose to pass arguments as named flags rather than command line
|
1916
|
+
arguments. Set `:use_flags` when expanding the template:
|
1917
|
+
|
1918
|
+
# In .toys.rb
|
1919
|
+
expand :rake, use_flags: true
|
1920
|
+
|
1921
|
+
Now with this option, to pass arguments to the tool, use the argument names as
|
1922
|
+
flags:
|
1923
|
+
|
1924
|
+
toys my_task --first=value1 --second=value2
|
1925
|
+
|
1712
1926
|
### From Rakefiles to Toys Files
|
1713
1927
|
|
1714
|
-
|
1715
|
-
|
1928
|
+
Invoking Rake tasks using Toys is an easy first step, but eventually you will
|
1929
|
+
likely want to migrate some of your project's build tasks from Rake to Toys.
|
1930
|
+
The remainder of this section describes the common patterns and features Toys
|
1931
|
+
provides for writing build tasks that are traditionally done with Rake.
|
1716
1932
|
|
1717
|
-
|
1718
|
-
|
1719
|
-
|
1720
|
-
this:
|
1933
|
+
Many common Rake tasks can be generated using code provided by either Rake or
|
1934
|
+
the third party library. Different libraries provide different mechanisms for
|
1935
|
+
task generation. For example, a test task might be defined like this:
|
1721
1936
|
|
1722
1937
|
require "rake/testtask"
|
1723
1938
|
Rake::TestTask.new do |t|
|
data/lib/toys.rb
CHANGED
@@ -30,10 +30,13 @@
|
|
30
30
|
;
|
31
31
|
|
32
32
|
##
|
33
|
-
# Toys is a
|
34
|
-
#
|
35
|
-
#
|
36
|
-
#
|
33
|
+
# Toys is a configurable command line tool. Write commands in config files
|
34
|
+
# using a simple DSL, and Toys will provide the command line binary and take
|
35
|
+
# care of all the details such as argument parsing, online help, and error
|
36
|
+
# reporting. Toys is designed for software developers, IT professionals, and
|
37
|
+
# other power users who want to write and organize scripts to automate their
|
38
|
+
# workflows. It can also be used as a Rake replacement, providing a more
|
39
|
+
# natural command line interface for your project's build tasks.
|
37
40
|
#
|
38
41
|
module Toys
|
39
42
|
##
|
data/lib/toys/standard_cli.rb
CHANGED
@@ -61,12 +61,36 @@ module Toys
|
|
61
61
|
#
|
62
62
|
INDEX_FILE_NAME = ".toys.rb"
|
63
63
|
|
64
|
+
##
|
65
|
+
# Standard preload directory name in a toys configuration
|
66
|
+
# @return [String]
|
67
|
+
#
|
68
|
+
PRELOAD_DIRECTORY_NAME = ".preload"
|
69
|
+
|
70
|
+
##
|
71
|
+
# Standard preload file name in a toys configuration
|
72
|
+
# @return [String]
|
73
|
+
#
|
74
|
+
PRELOAD_FILE_NAME = ".preload.rb"
|
75
|
+
|
76
|
+
##
|
77
|
+
# Standard data directory name in a toys configuration
|
78
|
+
# @return [String]
|
79
|
+
#
|
80
|
+
DATA_DIRECTORY_NAME = ".data"
|
81
|
+
|
64
82
|
##
|
65
83
|
# Name of standard toys binary
|
66
84
|
# @return [String]
|
67
85
|
#
|
68
86
|
BINARY_NAME = "toys"
|
69
87
|
|
88
|
+
##
|
89
|
+
# Delimiter characters recognized
|
90
|
+
# @return [String]
|
91
|
+
#
|
92
|
+
EXTRA_DELIMITERS = ":."
|
93
|
+
|
70
94
|
##
|
71
95
|
# Short description for the standard root tool
|
72
96
|
# @return [String]
|
@@ -78,9 +102,10 @@ module Toys
|
|
78
102
|
# @return [String]
|
79
103
|
#
|
80
104
|
DEFAULT_ROOT_LONG_DESC =
|
81
|
-
"Toys is your personal command line tool. You can
|
82
|
-
"
|
83
|
-
"
|
105
|
+
"Toys is your personal command line tool. You can write commands using a simple Ruby DSL," \
|
106
|
+
" and Toys will automatically organize them, parse arguments, and provide documentation." \
|
107
|
+
" Tools can be global or scoped to specific directories. You can also use Toys instead of" \
|
108
|
+
" Rake to provide build and maintenance scripts for your projects." \
|
84
109
|
" For detailed information, see https://www.rubydoc.info/gems/toys"
|
85
110
|
|
86
111
|
##
|
@@ -103,6 +128,10 @@ module Toys
|
|
103
128
|
config_dir_name: CONFIG_DIR_NAME,
|
104
129
|
config_file_name: CONFIG_FILE_NAME,
|
105
130
|
index_file_name: INDEX_FILE_NAME,
|
131
|
+
preload_file_name: PRELOAD_FILE_NAME,
|
132
|
+
preload_directory_name: PRELOAD_DIRECTORY_NAME,
|
133
|
+
data_directory_name: DATA_DIRECTORY_NAME,
|
134
|
+
extra_delimiters: EXTRA_DELIMITERS,
|
106
135
|
middleware_stack: default_middleware_stack,
|
107
136
|
template_lookup: default_template_lookup
|
108
137
|
)
|
@@ -154,6 +183,7 @@ module Toys
|
|
154
183
|
:show_help,
|
155
184
|
help_flags: true,
|
156
185
|
usage_flags: true,
|
186
|
+
list_flags: true,
|
157
187
|
recursive_flags: true,
|
158
188
|
search_flags: true,
|
159
189
|
default_recursive: true,
|
@@ -0,0 +1,123 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Copyright 2018 Daniel Azuma
|
4
|
+
#
|
5
|
+
# All rights reserved.
|
6
|
+
#
|
7
|
+
# Redistribution and use in source and binary forms, with or without
|
8
|
+
# modification, are permitted provided that the following conditions are met:
|
9
|
+
#
|
10
|
+
# * Redistributions of source code must retain the above copyright notice,
|
11
|
+
# this list of conditions and the following disclaimer.
|
12
|
+
# * Redistributions in binary form must reproduce the above copyright notice,
|
13
|
+
# this list of conditions and the following disclaimer in the documentation
|
14
|
+
# and/or other materials provided with the distribution.
|
15
|
+
# * Neither the name of the copyright holder, nor the names of any other
|
16
|
+
# contributors to this software, may be used to endorse or promote products
|
17
|
+
# derived from this software without specific prior written permission.
|
18
|
+
#
|
19
|
+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
20
|
+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
21
|
+
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
22
|
+
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
23
|
+
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
24
|
+
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
25
|
+
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
26
|
+
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
27
|
+
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
28
|
+
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
29
|
+
# POSSIBILITY OF SUCH DAMAGE.
|
30
|
+
;
|
31
|
+
|
32
|
+
module Toys
|
33
|
+
module Templates
|
34
|
+
##
|
35
|
+
# A template that generates tools matching a rakefile.
|
36
|
+
#
|
37
|
+
class Rake
|
38
|
+
include Template
|
39
|
+
|
40
|
+
##
|
41
|
+
# Default path to the Rakefile.
|
42
|
+
# @return [String]
|
43
|
+
#
|
44
|
+
DEFAULT_RAKEFILE_PATH = "Rakefile"
|
45
|
+
|
46
|
+
##
|
47
|
+
# Create the template settings for the rake template.
|
48
|
+
#
|
49
|
+
# @param [String,Array<String>,nil] gem_version Version requirements for
|
50
|
+
# the rake gem. Defaults to nil, indicating no version requirement.
|
51
|
+
# @param [String] rakefile_path Path to the Rakefile. Defaults to
|
52
|
+
# {DEFAULT_RAKEFILE_PATH}.
|
53
|
+
# @param [Boolean] only_described Tools are generated only for rake tasks
|
54
|
+
# with descriptions. Default is false.
|
55
|
+
# @param [Boolean] use_flags Generated tools use flags instead of
|
56
|
+
# positional arguments to pass arguments to rake tasks. Default is
|
57
|
+
# false.
|
58
|
+
#
|
59
|
+
def initialize(gem_version: nil,
|
60
|
+
rakefile_path: nil,
|
61
|
+
only_described: false,
|
62
|
+
use_flags: false)
|
63
|
+
@gem_version = gem_version
|
64
|
+
@rakefile_path = rakefile_path || DEFAULT_RAKEFILE_PATH
|
65
|
+
@only_described = only_described
|
66
|
+
@use_flags = use_flags
|
67
|
+
end
|
68
|
+
|
69
|
+
attr_accessor :gem_version
|
70
|
+
attr_accessor :rakefile_path
|
71
|
+
attr_accessor :only_described
|
72
|
+
attr_accessor :use_flags
|
73
|
+
|
74
|
+
to_expand do |template|
|
75
|
+
gem "rake", *Array(template.gem_version)
|
76
|
+
require "rake"
|
77
|
+
::Rake::TaskManager.record_task_metadata = true
|
78
|
+
rake = ::Rake::Application.new
|
79
|
+
::Rake.application = rake
|
80
|
+
::Rake.load_rakefile(template.rakefile_path)
|
81
|
+
rake.tasks.each do |task|
|
82
|
+
comments = task.full_comment.to_s.split("\n")
|
83
|
+
next if comments.empty? && template.only_described
|
84
|
+
tool(task.name.split(":"), if_defined: :ignore) do
|
85
|
+
unless comments.empty?
|
86
|
+
desc(comments.first)
|
87
|
+
long_desc(*comments)
|
88
|
+
end
|
89
|
+
if template.use_flags
|
90
|
+
task.arg_names.each do |arg|
|
91
|
+
specs = Templates::Rake.flag_specs(arg)
|
92
|
+
flag(arg, *specs) unless specs.empty?
|
93
|
+
end
|
94
|
+
to_run do
|
95
|
+
args = task.arg_names.map { |arg| self[arg] }
|
96
|
+
task.invoke(*args)
|
97
|
+
end
|
98
|
+
else
|
99
|
+
task.arg_names.each do |arg|
|
100
|
+
optional_arg(arg)
|
101
|
+
end
|
102
|
+
to_run do
|
103
|
+
task.invoke(*args)
|
104
|
+
end
|
105
|
+
end
|
106
|
+
end
|
107
|
+
end
|
108
|
+
end
|
109
|
+
|
110
|
+
## @private
|
111
|
+
def self.flag_specs(arg)
|
112
|
+
name = arg.to_s.gsub(/\W/, "").downcase
|
113
|
+
specs = []
|
114
|
+
unless name.empty?
|
115
|
+
specs << "--#{name}=VALUE"
|
116
|
+
name2 = name.tr("_", "-")
|
117
|
+
specs << "--#{name2}=VALUE" unless name2 == name
|
118
|
+
end
|
119
|
+
specs
|
120
|
+
end
|
121
|
+
end
|
122
|
+
end
|
123
|
+
end
|
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.
|
4
|
+
version: 0.5.0
|
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-08
|
11
|
+
date: 2018-10-08 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: toys-core
|
@@ -16,14 +16,28 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - '='
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: 0.
|
19
|
+
version: 0.5.0
|
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.
|
26
|
+
version: 0.5.0
|
27
|
+
- !ruby/object:Gem::Dependency
|
28
|
+
name: highline
|
29
|
+
requirement: !ruby/object:Gem::Requirement
|
30
|
+
requirements:
|
31
|
+
- - "~>"
|
32
|
+
- !ruby/object:Gem::Version
|
33
|
+
version: '2.0'
|
34
|
+
type: :development
|
35
|
+
prerelease: false
|
36
|
+
version_requirements: !ruby/object:Gem::Requirement
|
37
|
+
requirements:
|
38
|
+
- - "~>"
|
39
|
+
- !ruby/object:Gem::Version
|
40
|
+
version: '2.0'
|
27
41
|
- !ruby/object:Gem::Dependency
|
28
42
|
name: minitest
|
29
43
|
requirement: !ruby/object:Gem::Requirement
|
@@ -66,34 +80,48 @@ dependencies:
|
|
66
80
|
- - "~>"
|
67
81
|
- !ruby/object:Gem::Version
|
68
82
|
version: '5.2'
|
83
|
+
- !ruby/object:Gem::Dependency
|
84
|
+
name: redcarpet
|
85
|
+
requirement: !ruby/object:Gem::Requirement
|
86
|
+
requirements:
|
87
|
+
- - "~>"
|
88
|
+
- !ruby/object:Gem::Version
|
89
|
+
version: '3.4'
|
90
|
+
type: :development
|
91
|
+
prerelease: false
|
92
|
+
version_requirements: !ruby/object:Gem::Requirement
|
93
|
+
requirements:
|
94
|
+
- - "~>"
|
95
|
+
- !ruby/object:Gem::Version
|
96
|
+
version: '3.4'
|
69
97
|
- !ruby/object:Gem::Dependency
|
70
98
|
name: rubocop
|
71
99
|
requirement: !ruby/object:Gem::Requirement
|
72
100
|
requirements:
|
73
101
|
- - "~>"
|
74
102
|
- !ruby/object:Gem::Version
|
75
|
-
version: 0.
|
103
|
+
version: 0.59.1
|
76
104
|
type: :development
|
77
105
|
prerelease: false
|
78
106
|
version_requirements: !ruby/object:Gem::Requirement
|
79
107
|
requirements:
|
80
108
|
- - "~>"
|
81
109
|
- !ruby/object:Gem::Version
|
82
|
-
version: 0.
|
110
|
+
version: 0.59.1
|
83
111
|
- !ruby/object:Gem::Dependency
|
84
112
|
name: yard
|
85
113
|
requirement: !ruby/object:Gem::Requirement
|
86
114
|
requirements:
|
87
115
|
- - "~>"
|
88
116
|
- !ruby/object:Gem::Version
|
89
|
-
version: 0.9.
|
117
|
+
version: 0.9.16
|
90
118
|
type: :development
|
91
119
|
prerelease: false
|
92
120
|
version_requirements: !ruby/object:Gem::Requirement
|
93
121
|
requirements:
|
94
122
|
- - "~>"
|
95
123
|
- !ruby/object:Gem::Version
|
96
|
-
version: 0.9.
|
124
|
+
version: 0.9.16
|
97
125
|
description: Toys is a configurable command line tool. Write commands in config files
|
98
126
|
using a simple DSL, and Toys will provide the command line binary and take care
|
99
127
|
of all the details such as argument parsing, online help, and error reporting. Toys
|
@@ -121,6 +149,7 @@ files:
|
|
121
149
|
- lib/toys/templates/clean.rb
|
122
150
|
- lib/toys/templates/gem_build.rb
|
123
151
|
- lib/toys/templates/minitest.rb
|
152
|
+
- lib/toys/templates/rake.rb
|
124
153
|
- lib/toys/templates/rdoc.rb
|
125
154
|
- lib/toys/templates/rubocop.rb
|
126
155
|
- lib/toys/templates/yardoc.rb
|
@@ -128,7 +157,11 @@ files:
|
|
128
157
|
homepage: https://github.com/dazuma/toys
|
129
158
|
licenses:
|
130
159
|
- BSD-3-Clause
|
131
|
-
metadata:
|
160
|
+
metadata:
|
161
|
+
changelog_uri: https://github.com/dazuma/toys/blob/master/toys/CHANGELOG.md
|
162
|
+
source_code_uri: https://github.com/dazuma/toys
|
163
|
+
bug_tracker_uri: https://github.com/dazuma/toys/issues
|
164
|
+
documentation_uri: https://www.rubydoc.info/gems/toys
|
132
165
|
post_install_message:
|
133
166
|
rdoc_options: []
|
134
167
|
require_paths:
|