0.08
Fourchette is your new best friend for having isolated testing environment. It will help you test your GitHub PRs against a fork of one your Heroku apps. You will have one Heroku app per PR now. Isn't that amazing? It will make testing way easier and you won't have the (maybe) broken code from other PRs on staging but only the code that requires testing.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
Activity
0.0
GQLite is a C++-language library, with a C interface, that implements a small, fast, self-contained, high-reliability, full-featured, Graph Query database engine. The data is stored in a SQLite database, which the fasted and most used SQL database. This enable to achieve high performance and for application to combine Graph queries with traditional SQL queries.
GQLite source code is license under the [MIT License](LICENSE) and is free to everyone to use for any purpose.
The official repositories contains bindings/APIs for C, C++, Python, Ruby and Crystal.
The library is still in its early stage, but it is now fully functional. Development effort has now slowed down and new features are added on a by-need basis. It supports a subset of [OpenCypher](https://opencypher.org/), and the intent is to also support ISO GQL in the future when it become available.
Example of use
--------------
```ruby
require 'gqlite'
begin
# Create a database on the file "test.db"
connection = GQLite::Connection.new sqlite_filename: "test.db"
# Execute a simple query to create a node and return all the nodes
value = connection.execute_oc_query("CREATE () MATCH (n) RETURN n")
# Print the result
if value.nil?
puts "Empty results"
else
puts "Results are #{value.to_s}"
end
rescue GQLite::Error => ex
# Report any error
puts "An error has occured: #{ex.message}"
end
```
The documentation for the openCypher query language can found in [openCypher](https://gitlab.com/gqlite/GQLite/-/blob/docs/opencypher.md) and for the [API](https://gitlab.com/gqlite/GQLite/-/blob/docs/api.md).
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
Activity
0.0
# Trope
**[Documentation][docs] - [Gem][gems] - [Source][source]**
Prototyping language that transcompiles into pure Ruby code.
1. Build your concept in Trope.
2. Write specs.
3. Transcompile into Ruby.
4. Destroy Trope files.
5. Red, green, refactor.
## Install
> NOTE: Trope is not released yet, the gem is just a placeholder.
### Bundler: `gem 'trope'`
### RubyGems: `gem install trope`
## Example
Create `library.trope`:
```ruby
object Book
attr name <String> -!wd 'Unnamed book'
attr isbn <Integer> -w
attr library <Library> -w do
before write { @library.books.delete(self) unless @library.nil? }
after write { @library.books.push(self) unless @library.books.include?(self) }
end
end
object Library
attr books <Array> -d Array.new
meth add_book do |attributes_or_book <Hash, Book>|
book = attributes_or_book.is_a?(Book) ? attributes_or_book : Book.new(attributes_or_book)
book.library = self
@books << book
end
end
```
Now generate the Ruby code:
```sh
$ trope compile libary.trope
```
Those 15 lines will be transcompiled into the following pure Ruby code in `library.rb`:
```ruby
class Book
class Error < RuntimeError; end
class InvalidAttributesError < Error
def to_s
'attributes must be a Hash or respond to #to_h'
end
end
class MissingAttributeError < Error
def initialize(attr_name, attr_class)
@name, @class = attr_name.to_s, attr_class.to_s
end
def to_s
"attribute '#@name' does not exist for #@class"
end
end
class MissingNameError < Error
def to_s
'name cannot be nil'
end
end
class InvalidNameError < Error
def to_s
'name must be an instance of String or respond to :to_s'
end
end
class InvalidIsbnError < Error
def to_s
'isbn must be an instance of Integer or respond to :to_i'
end
end
class MissingLibraryError < Error
def to_s
'library cannot be nil'
end
end
class InvalidLibraryError < Error
def to_s
'library must be an instance of Library'
end
end
attr_reader *(@@_attributes = [:name, :isbn, :library])
def initialize(attributes={})
raise InvalidAttributesError unless attributes.is_a?(Hash) || attributes.respond_to?(:to_h)
attributes = attributes.to_h unless attributes.is_a?(Hash)
raise MissingNameError if attributes.has_key?(:name) && attributes[:name].nil?
attributes[:name] = 'Unnamed book' unless attributes.has_key?(:name)
attributes.each do |name, value|
raise MissingAttributeError.new(name, self.class) unless @@_attributes.include?(name.to_sym)
setter_method = "#{name}="
setter_method = "_#{setter_method}" unless self.class.method_defined?(setter_method)
send(setter_method, value)
end
end
def name=(value)
raise MissingNameError if value.nil?
raise InvalidNameError unless value.is_a?(String) || value.respond_to?(:to_s)
value = value.to_i unless value.is_a?(Integer)
@name = value
end
def isbn=(value)
raise InvalidIsbnError unless value.is_a?(Integer) || value.respond_to?(:to_i)
value = value.to_i unless value.is_a?(Integer)
@isbn = value
end
def library=(value)
raise InvalidLibraryError unless value.is_a?(Library) || value.nil?
@library.books.delete(self) unless @library.nil?
@library = value
@library.books.push(self) unless @library.books.include?(self)
@library
end
end
class Library
class Error < RuntimeError; end
class InvalidAttributesError < Error
def to_s
'attributes must be an instance of Hash or respond to #to_h'
end
end
class MissingAttributeError < Error
def initialize(attr_name, attr_class)
@name, @class = attr_name.to_s, attr_class.to_s
end
def to_s
"attribute '#@name' does not exist for #@class"
end
end
class InvalidBooksError < Error
def to_s
'books must be an instance of Array or respond to #to_a'
end
end
attr_reader *(@@_attributes = [:books])
def initialize(attributes={})
raise InvalidAttributesError unless attributes.is_a?(Hash) || attributes.respond_to?(:to_h)
attributes = attributes.to_h unless attributes.is_a?(Hash)
attributes[:books] = Array.new unless attributes.has_key?(:books)
attributes.each do |name, value|
raise MissingAttributeError.new(name, self.class) unless @@_attributes.include?(name.to_sym)
setter_method = "#{name}="
setter_method = "_#{setter_method}" unless self.class.method_defined?(setter_method)
send(setter_method, value)
end
end
def add_book(attributes_or_book={})
raise InvalidAttributesError unless attributes_or_book.is_a?(Hash) || attributes_or_book.respond_to?(:to_h) || attributes_or_book.is_a?(Book)
attributes_or_book = attributes_or_book.to_h unless attributes_or_book.is_a?(Hash) || attributes_or_book.is_a?(Book)
book = attributes_or_book.is_a?(Book) ? attributes_or_book : Book.new(attributes_or_book)
book.library = self
@books << book
end
protected
def _books=(value)
raise InvalidBooksError unless value.is_a?(Array) || value.respond_to?(:to_a)
value = value.to_a unless value.is_a?(Array)
@books = value
end
end
```
Using the transcompiled Ruby code will produce the expected results:
```ruby
p library = Library.new # => #<Library:0x007fc55c0ce418 @books=[]>
p library.add_book name: 'Book 1', isbn: 1 # => [#<Book:0x007fc55c0cde78 @name=0, @isbn=1, @library=#<Library:0x007fc55c0ce418 @books=[...]>>]
p library # => #<Library:0x007fc55c0ce418 @books=[#<Book:0x007fc55c0cde78 @name=0, @isbn=1, @library=#<Library:0x007fc55c0ce418 ...>>]>
p library.books.first # => #<Book:0x007fc55c0cde78 @name=0, @isbn=1, @library=#<Library:0x007fc55c0ce418 @books=[#<Book:0x007fc55c0cde78 ...>]>>
p library.books.first.isbn = nil # => nil
p library.books.first.name = nil # => Book::MissingNameError: name cannot be nil
p library.books.first.library = nil # => Book::MissingLibraryError: library cannot be nil
p library.books.first.isbn = ['array'] # => Book::InvalidIsbnError: isbn must be an instance of Integer or respond to :to_i
p library = Library.new(books: 123) # => Library::InvalidBooksError: books must be an instance of Array or respond to #to_a
```
### Breakdown
```ruby
object Book
attr name <String> -!wd 'Unnamed book'
end
```
This says that I have an object `Book` that has an attribute `name` (`attr name`) that
must either be an instance/subclass of `String` or be able to convert to an instance of
`String` using `#to_s` (`<String>`). It is a required attribute that can never be set to nil (`!`), has a writer method (`w`),
and defaults to 'Unnamed book'.
The minus sign (`-`) indicates a 'switch' or 'option', must like most *nix command line
programs. The example could also have been written like so:
```ruby
object Book
attr name <String> -! -w -d 'Unnamed book'
end
```
The above examples will transcompile into the following:
```ruby
class Book
class Error < RuntimeError; end
class InvalidAttributesError < Error
def to_s
'attributes must be a Hash or respond to #to_h'
end
end
class MissingAttributeError < Error
def initialize(attr_name, attr_class)
@name, @class = attr_name.to_s, attr_class.to_s
end
def to_s
"attribute '#@name' does not exist for #@class"
end
end
class MissingNameError < Error
def to_s
'name cannot be nil'
end
end
class InvalidNameError < Error
def to_s
'name must be an instance of String or respond to :to_s'
end
end
attr_reader *(@@_attributes = [:name])
@@_required_attributes = [:name]
def initialize(attributes={})
raise InvalidAttributesError unless attributes.is_a?(Hash) || attributes.respond_to?(:to_h)
attributes = attributes.to_h unless attributes.is_a?(Hash)
raise MissingNameError if attributes.has_key?(:name) && attributes[:name].nil?
attributes[:name] = 'Unnamed book' unless attributes.has_key?(:name)
attributes.each do |name, value|
raise MissingAttributeError.new(name, self.class) unless @@_attributes.include?(name.to_sym)
setter_method = "#{name}="
setter_method = "_#{setter_method}" unless self.class.method_defined?(setter_method)
send(setter_method, value)
end
end
def name=(value)
raise MissingNameError if value.nil?
raise InvalidNameError unless value.is_a?(String) || value.respond_to?(:to_s)
value = value.to_i unless value.is_a?(Integer)
@name = value
end
end
```
## Contributing
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, VERSION, or Gemfile. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
## Copyright
Copyright © 2012 Ryan Scott Lewis <ryan@rynet.us>.
The MIT License (MIT) - See LICENSE for further details.
[docs]: http://rubydoc.info/gems/trope/frames
[gems]: https://rubygems.org/gems/trope
[source]: https://github.com/RyanScottLewis/trope
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
Activity
0.0
Lookout
Lookout is a unit testing framework for Ruby┬╣ that puts your results in
focus. Tests (expectations) are written as follows
expect 2 do
1 + 1
end
expect ArgumentError do
Integer('1 + 1')
end
expect Array do
[1, 2, 3].select{ |i| i % 2 == 0 }
end
expect [2, 4, 6] do
[1, 2, 3].map{ |i| i * 2 }
end
Lookout is designed to encourage ΓÇô force, even ΓÇô unit testing best practices
such as
ΓÇó Setting up only one expectation per test
ΓÇó Not setting expectations on non-public APIs
ΓÇó Test isolation
This is done by
ΓÇó Only allowing one expectation to be set per test
ΓÇó Providing no (additional) way of accessing private state
ΓÇó Providing no setup and tear-down methods, nor a method of providing test
helpers
Other important points are
ΓÇó Putting the expected outcome of a test in focus with the steps of the
calculation of the actual result only as a secondary concern
ΓÇó A focus on code readability by providing no mechanism for describing an
expectation other than the code in the expectation itself
ΓÇó A unified syntax for setting up both state-based and behavior-based
expectations
The way Lookout works has been heavily influenced by expectations┬▓, by
{Jay Fields}┬│. The code base was once also heavily based on expectations,
based at Subversion {revision 76}⁴. A lot has happened since then and all of
the work past that revision are due to {Nikolai Weibull}⁵.
┬╣ Ruby: http://ruby-lang.org/
┬▓ Expectations: http://expectations.rubyforge.org/
┬│ Jay FieldsΓÇÖs blog: http://blog.jayfields.com/
⁴ Lookout revision 76:
https://github.com/now/lookout/commit/537bedf3e5b3eb4b31c066b3266f42964ac35ebe
⁵ Nikolai Weibull’s home page: http://disu.se/
§ Installation
Install Lookout with
% gem install lookout
§ Usage
Lookout allows you to set expectations on an objectΓÇÖs state or behavior.
WeΓÇÖll begin by looking at state expectations and then take a look at
expectations on behavior.
§ Expectations on State: Literals
An expectation can be made on the result of a computation:
expect 2 do
1 + 1
end
Most objects, in fact, have their state expectations checked by invoking
‹#==› on the expected value with the result as its argument.
Checking that a result is within a given range is also simple:
expect 0.099..0.101 do
0.4 - 0.3
end
Here, the more general ‹#===› is being used on the ‹Range›.
§ Regexps
‹Strings› of course match against ‹Strings›:
expect 'ab' do
'abc'[0..1]
end
but we can also match a ‹String› against a ‹Regexp›:
expect %r{a substring} do
'a string with a substring'
end
(Note the use of ‹%r{…}› to avoid warnings that will be generated when
Ruby parses ‹expect /…/›.)
§ Modules
Checking that the result includes a certain module is done by expecting the
‹Module›.
expect Enumerable do
[]
end
This, due to the nature of Ruby, of course also works for classes (as
they are also modules):
expect String do
'a string'
end
This doesn’t hinder us from expecting the actual ‹Module› itself:
expect Enumerable do
Enumerable
end
or the ‹Class›:
expect String do
String
end
for obvious reasons.
As you may have figured out yourself, this is accomplished by first
trying ‹#==› and, if it returns ‹false›, then trying ‹#===› on the
expected ‹Module›. This is also true of ‹Ranges› and ‹Regexps›.
§ Booleans
Truthfulness is expected with ‹true› and ‹false›:
expect true do
1
end
expect false do
nil
end
Results equaling ‹true› or ‹false› are slightly different:
expect TrueClass do
true
end
expect FalseClass do
false
end
The rationale for this is that you should only care if the result of a
computation evaluates to a value that Ruby considers to be either true or
false, not the exact literals ‹true› or ‹false›.
§ IO
Expecting output on an IO object is also common:
expect output("abc\ndef\n") do |io|
io.puts 'abc', 'def'
end
This can be used to capture the output of a formatter that takes an
output object as a parameter.
§ Warnings
Expecting warnings from code isnΓÇÖt very common, but should be done:
expect warning('this is your final one!') do
warn 'this is your final one!'
end
expect warning('this is your final one!') do
warn '%s:%d: warning: this is your final one!' % [__FILE__, __LINE__]
end
‹$VERBOSE› is set to ‹true› during the execution of the block, so you
donΓÇÖt need to do so yourself. If you have other code that depends on the
value of $VERBOSE, that can be done with ‹#with_verbose›
expect nil do
with_verbose nil do
$VERBOSE
end
end
§ Errors
You should always be expecting errors from ΓÇô and in, but thatΓÇÖs a
different story ΓÇô your code:
expect ArgumentError do
Integer('1 + 1')
end
Often, not only the type of the error, but its description, is important
to check:
expect StandardError.new('message') do
raise StandardError.new('message')
end
As with ‹Strings›, ‹Regexps› can be used to check the error description:
expect StandardError.new(/mess/) do
raise StandardError.new('message')
end
§ Queries Through Symbols
Symbols are generally matched against symbols, but as a special case,
symbols ending with ‹?› are seen as expectations on the result of query
methods on the result of the block, given that the method is of zero
arity and that the result isnΓÇÖt a Symbol itself. Simply expect a symbol
ending with ‹?›:
expect :empty? do
[]
end
To expect it’s negation, expect the same symbol beginning with ‹not_›:
expect :not_nil? do
[1, 2, 3]
end
This is the same as
expect true do
[].empty?
end
and
expect false do
[1, 2, 3].empty?
end
but provides much clearer failure messages. It also makes the
expectationΓÇÖs intent a lot clearer.
§ Queries By Proxy
ThereΓÇÖs also a way to make the expectations of query methods explicit by
invoking methods on the result of the block. For example, to check that
the even elements of the Array ‹[1, 2, 3]› include ‹1› you could write
expect result.to.include? 1 do
[1, 2, 3].reject{ |e| e.even? }
end
You could likewise check that the result doesnΓÇÖt include 2:
expect result.not.to.include? 2 do
[1, 2, 3].reject{ |e| e.even? }
end
This is the same as (and executes a little bit slower than) writing
expect false do
[1, 2, 3].reject{ |e| e.even? }.include? 2
end
but provides much clearer failure messages. Given that these two last
examples would fail, youΓÇÖd get a message saying ΓÇ£[1, 2, 3]#include?(2)ΓÇ¥
instead of the terser ΓÇ£trueΓëáfalseΓÇ¥. It also clearly separates the actual
expectation from the set-up.
The keyword for this kind of expectations is ‹result›. This may be
followed by any of the methods
• ‹#not›
• ‹#to›
• ‹#be›
• ‹#have›
or any other method you will want to call on the result. The methods
‹#to›, ‹#be›, and ‹#have› do nothing except improve readability. The
‹#not› method inverts the expectation.
§ Literal Literals
If you need to literally check against any of the types of objects
otherwise treated specially, that is, any instances of
• ‹Module›
• ‹Range›
• ‹Regexp›
• ‹Exception›
• ‹Symbol›, given that it ends with ‹?›
you can do so by wrapping it in ‹literal(…)›:
expect literal(:empty?) do
:empty?
end
You almost never need to do this, as, for all but symbols, instances will
match accordingly as well.
§ Expectations on Behavior
We expect our objects to be on their best behavior. Lookout allows you
to make sure that they are.
Reception expectations let us verify that a method is called in the way
that we expect it to be:
expect mock.to.receive.to_str(without_arguments){ '123' } do |o|
o.to_str
end
Here, ‹#mock› creates a mock object, an object that doesn’t respond to
anything unless you tell it to. We tell it to expect to receive a call
to ‹#to_str› without arguments and have ‹#to_str› return ‹'123'› when
called. The mock object is then passed in to the block so that the
expectations placed upon it can be fulfilled.
Sometimes we only want to make sure that a method is called in the way
that we expect it to be, but we donΓÇÖt care if any other methods are
called on the object. A stub object, created with ‹#stub›, expects any
method and returns a stub object that, again, expects any method, and
thus fits the bill.
expect stub.to.receive.to_str(without_arguments){ '123' } do |o|
o.to_str if o.convertable?
end
You donΓÇÖt have to use a mock object to verify that a method is called:
expect Object.to.receive.name do
Object.name
end
As you have figured out by now, the expected method call is set up by
calling ‹#receive› after ‹#to›. ‹#Receive› is followed by a call to the
method to expect with any expected arguments. The body of the expected
method can be given as the block to the method. Finally, an expected
invocation count may follow the method. LetΓÇÖs look at this formal
specification in more detail.
The expected method arguments may be given in a variety of ways. LetΓÇÖs
introduce them by giving some examples:
expect mock.to.receive.a do |m|
m.a
end
Here, the method ‹#a› must be called with any number of arguments. It
may be called any number of times, but it must be called at least once.
If a method must receive exactly one argument, you can use ‹Object›, as
the same matching rules apply for arguments as they do for state
expectations:
expect mock.to.receive.a(Object) do |m|
m.a 0
end
If a method must receive a specific argument, you can use that argument:
expect mock.to.receive.a(1..2) do |m|
m.a 1
end
Again, the same matching rules apply for arguments as they do for state
expectations, so the previous example expects a call to ‹#a› with 1, 2,
or the Range 1..2 as an argument on ‹m›.
If a method must be invoked without any arguments you can use
‹without_arguments›:
expect mock.to.receive.a(without_arguments) do |m|
m.a
end
You can of course use both ‹Object› and actual arguments:
expect mock.to.receive.a(Object, 2, Object) do |m|
m.a nil, 2, '3'
end
The body of the expected method may be given as the block. Here, calling
‹#a› on ‹m› will give the result ‹1›:
expect mock.to.receive.a{ 1 } do |m|
raise 'not 1' unless m.a == 1
end
If no body has been given, the result will be a stub object.
To take a block, grab a block parameter and ‹#call› it:
expect mock.to.receive.a{ |&b| b.call(1) } do |m|
j = 0
m.a{ |i| j = i }
raise 'not 1' unless j == 1
end
To simulate an ‹#each›-like method, ‹#call› the block several times.
Invocation count expectations can be set if the default expectation of
ΓÇ£at least onceΓÇ¥ isnΓÇÖt good enough. The following expectations are
possible
• ‹#at_most_once›
• ‹#once›
• ‹#at_least_once›
• ‹#twice›
And, for a given ‹N›,
• ‹#at_most(N)›
• ‹#exactly(N)›
• ‹#at_least(N)›
§ Utilities: Stubs
Method stubs are another useful thing to have in a unit testing
framework. Sometimes you need to override a method that does something a
test shouldnΓÇÖt do, like access and alter bank accounts. We can override
– stub out – a method by using the ‹#stub› method. Let’s assume that we
have an ‹Account› class that has two methods, ‹#slips› and ‹#total›.
‹#Slips› retrieves the bank slips that keep track of your deposits to the
‹Account› from a database. ‹#Total› sums the ‹#slips›. In the following
test we want to make sure that ‹#total› does what it should do without
accessing the database. We therefore stub out ‹#slips› and make it
return something that we can easily control.
expect 6 do |m|
stub(Class.new{
def slips
raise 'database not available'
end
def total
slips.reduce(0){ |m, n| m.to_i + n.to_i }
end
}.new, :slips => [1, 2, 3]){ |account| account.total }
end
To make it easy to create objects with a set of stubbed methods thereΓÇÖs
also a convenience method:
expect 3 do
s = stub(:a => 1, :b => 2)
s.a + s.b
end
This short-hand notation can also be used for the expected value:
expect stub(:a => 1, :b => 2).to.receive.a do |o|
o.a + o.b
end
and also works for mock objects:
expect mock(:a => 2, :b => 2).to.receive.a do |o|
o.a + o.b
end
Blocks are also allowed when defining stub methods:
expect 3 do
s = stub(:a => proc{ |a, b| a + b })
s.a(1, 2)
end
If need be, we can stub out a specific method on an object:
expect 'def' do
stub('abc', :to_str => 'def'){ |a| a.to_str }
end
The stub is active during the execution of the block.
§ Overriding Constants
Sometimes you need to override the value of a constant during the
execution of some code. Use ‹#with_const› to do just that:
expect 'hello' do
with_const 'A::B::C', 'hello' do
A::B::C
end
end
Here, the constant ‹A::B::C› is set to ‹'hello'› during the execution of
the block. None of the constants ‹A›, ‹B›, and ‹C› need to exist for
this to work. If a constant doesnΓÇÖt exist itΓÇÖs created and set to a new,
empty, ‹Module›. The value of ‹A::B::C›, if any, is restored after the
block returns and any constants that didnΓÇÖt previously exist are removed.
§ Overriding Environment Variables
Another thing you often need to control in your tests is the value of
environment variables. Depending on such global values is, of course,
not a good practice, but is often unavoidable when working with external
libraries. ‹#With_env› allows you to override the value of environment
variables during the execution of a block by giving it a ‹Hash› of
key/value pairs where the key is the name of the environment variable and
the value is the value that it should have during the execution of that
block:
expect 'hello' do
with_env 'INTRO' => 'hello' do
ENV['INTRO']
end
end
Any overridden values are restored and any keys that werenΓÇÖt previously a
part of the environment are removed when the block returns.
§ Overriding Globals
You may also want to override the value of a global temporarily:
expect 'hello' do
with_global :$stdout, StringIO.new do
print 'hello'
$stdout.string
end
end
You thus provide the name of the global and a value that it should take
during the execution of a block of code. The block gets passed the
overridden value, should you need it:
expect true do
with_global :$stdout, StringIO.new do |overridden|
$stdout != overridden
end
end
§ Integration
Lookout can be used from Rake┬╣. Simply install Lookout-Rake┬▓:
% gem install lookout-rake
and add the following code to your Rakefile
require 'lookout-rake-3.0'
Lookout::Rake::Tasks::Test.new
Make sure to read up on using Lookout-Rake for further benefits and
customization.
┬╣ Read more about Rake at http://rake.rubyforge.org/
┬▓ Get information on Lookout-Rake at http://disu.se/software/lookout-rake/
§ API
Lookout comes with an API┬╣ that letΓÇÖs you create things such as new
expected values, difference reports for your types, and so on.
┬╣ See http://disu.se/software/lookout/api/
§ Interface Design
The default output of Lookout can Spartanly be described as Spartan. If no
errors or failures occur, no output is generated. This is unconventional,
as unit testing frameworks tend to dump a lot of information on the user,
concerning things such as progress, test count summaries, and flamboyantly
colored text telling you that your tests passed. None of this output is
needed. Your tests should run fast enough to not require progress reports.
The lack of output provides you with the same amount of information as
reporting success. Test count summaries are only useful if youΓÇÖre worried
that your tests arenΓÇÖt being run, but if you worry about that, then
providing such output doesnΓÇÖt really help. Testing your tests requires
something beyond reporting some arbitrary count that you would have to
verify by hand anyway.
When errors or failures do occur, however, the relevant information is
output in a format that can easily be parsed by an ‹'errorformat'› for Vim
or with {Compilation Mode}┬╣ for Emacs┬▓. Diffs are generated for Strings,
Arrays, Hashes, and I/O.
┬╣ Read up on Compilation mode for Emacs at http://www.emacswiki.org/emacs/CompilationMode
┬▓ Visit The GNU FoundationΓÇÖs EmacsΓÇÖ software page at http://www.gnu.org/software/emacs/
§ External Design
LetΓÇÖs now look at some of the points made in the introduction in greater
detail.
Lookout only allows you to set one expectation per test. If youΓÇÖre testing
behavior with a reception expectation, then only one method-invocation
expectation can be set. If youΓÇÖre testing state, then only one result can
be verified. It may seem like this would cause unnecessary duplication
between tests. While this is certainly a possibility, when you actually
begin to try to avoid such duplication you find that you often do so by
improving your interfaces. This kind of restriction tends to encourage the
use of value objects, which are easy to test, and more focused objects,
which require simpler tests, as they have less behavior to test, per
method. By keeping your interfaces focused youΓÇÖre also keeping your tests
focused.
Keeping your tests focused improves, in itself, test isolation, but letΓÇÖs
look at something that hinders it: setup and tear-down methods. Most unit
testing frameworks encourage test fragmentation by providing setup and
tear-down methods.
Setup methods create objects and, perhaps, just their behavior for a set of
tests. This means that you have to look in two places to figure out whatΓÇÖs
being done in a test. This may work fine for few methods with simple
set-ups, but makes things complicated when the number of tests increases
and the set-up is complex. Often, each test further adjusts the previously
set-up object before performing any verifications, further complicating the
process of figuring out what state an object has in a given test.
Tear-down methods clean up after tests, perhaps by removing records from a
database or deleting files from the file-system.
The duplication that setup methods and tear-down methods hope to remove is
better avoided by improving your interfaces. This can be done by providing
better set-up methods for your objects and using idioms such as {Resource
Acquisition Is Initialization}┬╣ for guaranteed clean-up, test or no test.
By not using setup and tear-down methods we keep everything pertinent to a
test in the test itself, thus improving test isolation. (You also wonΓÇÖt
{slow down your tests}┬▓ by keeping unnecessary state.)
Most unit test frameworks also allow you to create arbitrary test helper
methods. Lookout doesnΓÇÖt. The same rationale as that that has been
crystallized in the preceding paragraphs applies. If you need helpers
youΓÇÖre interface isnΓÇÖt good enough. It really is as simple as that.
To clarify: thereΓÇÖs nothing inherently wrong with test helper methods, but
they should be general enough that they reside in their own library. The
support for mocks in Lookout is provided through a set of test helper
methods that make it easier to create mocks than it would have been without
them. Lookout-rack┬│ is another example of a library providing test helper
methods (well, one method, actually) that are very useful in testing web
applications that use Rack⁴.
A final point at which some unit test frameworks try to fragment tests
further is documentation. These frameworks provide ways of describing the
whats and hows of whatΓÇÖs being tested, the rationale being that this will
provide documentation of both the test and the code being tested.
Describing how a stack data structure is meant to work is a common example.
A stack is, however, a rather simple data structure, so such a description
provides little, if any, additional information that canΓÇÖt be extracted
from the implementation and its tests themselves. The implementation and
its tests is, in fact, its own best documentation. Taking the points made
in the previous paragraphs into account, we should already have simple,
self-describing, interfaces that have easily understood tests associated
with them. Rationales for the use of a given data structure or
system-design design documentation is better suited in separate
documentation focused at describing exactly those issues.
┬╣ Read the Wikipedia entry for Resource Acquisition Is Initialization at
http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization
┬▓ Read how 37signals had problems with slow Test::Unit tests at
http://37signals.com/svn/posts/2742-the-road-to-faster-tests/
┬│ Visit the Lookout-rack home page at
http://disu.se/software/lookout-rack/
⁴ Visit the Rack Rubyforge project page at
http://rack.rubyforge.org/
§ Internal Design
The internal design of Lookout has had a couple of goals.
ΓÇó As few external dependencies as possible
ΓÇó As few internal dependencies as possible
ΓÇó Internal extensibility provides external extensibility
ΓÇó As fast load times as possible
ΓÇó As high a ratio of value objects to mutable objects as possible
ΓÇó Each object must have a simple, obvious name
ΓÇó Use mix-ins, not inheritance for shared behavior
ΓÇó As few responsibilities per object as possible
ΓÇó Optimizing for speed can only be done when you have all the facts
§ External Dependencies
Lookout used to depend on Mocha for mocks and stubs. While benchmarking I
noticed that a method in Mocha was taking up more than 300 percent of the
runtime. It turned out that MochaΓÇÖs method for cleaning up back-traces
generated when a mock failed was doing something incredibly stupid:
backtrace.reject{ |l| Regexp.new(@lib).match(File.expand_path(l)) }
Here ‹@lib› is a ‹String› containing the path to the lib sub-directory in
the Mocha installation directory. I reported it, provided a patch five
days later, then waited. Nothing happened. {254 days later}┬╣, according
to {Wolfram Alpha}┬▓, half of my patch was, apparently ΓÇô I say ΓÇ£apparentlyΓÇ¥,
as I received no notification ΓÇô applied. By that time I had replaced the
whole mocking-and-stubbing subsystem and dropped the dependency.
Many Ruby developers claim that Ruby and its gems are too fast-moving for
normal package-managing systems to keep up. This is testament to the fact
that this isnΓÇÖt the case and that the real problem is instead related to
sloppy practices.
Please note that I donΓÇÖt want to single out the Mocha library nor its
developers. I only want to provide an example where relying on external
dependencies can be ΓÇ£considered harmfulΓÇ¥.
┬╣ See the Wolfram Alpha calculation at http://www.wolframalpha.com/input/?i=days+between+march+17%2C+2010+and+november+26%2C+2010
┬▓ Check out the Wolfram Alpha computational knowledge engine at http://www.wolframalpha.com/
§ Internal Dependencies
Lookout has been designed so as to keep each subsystem independent of any
other. The diff subsystem is, for example, completely decoupled from any
other part of the system as a whole and could be moved into its own library
at a time where that would be of interest to anyone. WhatΓÇÖs perhaps more
interesting is that the diff subsystem is itself very modular. The data
passes through a set of filters that depends on what kind of diff has been
requested, each filter yielding modified data as it receives it. If you
want to read some rather functional Ruby I can highly recommend looking at
the code in the ‹lib/lookout/diff› directory.
This lookout on the design of the library also makes it easy to extend
Lookout. Lookout-rack was, for example, written in about four hours and
about 5 of those 240 minutes were spent on setting up the interface between
the two.
§ Optimizing For Speed
The following paragraph is perhaps a bit personal, but might be interesting
nonetheless.
IΓÇÖve always worried about speed. The original Expectations library used
‹extend› a lot to add new behavior to objects. Expectations, for example,
used to hold the result of their execution (what we now term ΓÇ£evaluationΓÇ¥)
by being extended by a module representing success, failure, or error. For
the longest time I used this same method, worrying about the increased
performance cost that creating new objects for results would incur. I
finally came to a point where I felt that the code was so simple and clean
that rewriting this part of the code for a benchmark wouldnΓÇÖt take more
than perhaps ten minutes. Well, ten minutes later I had my results and
they confirmed that creating new objects wasnΓÇÖt harming performance. I was
very pleased.
§ Naming
I hate low lines (underscores). I try to avoid them in method names and I
always avoid them in file names. Since the current ΓÇ£best practiceΓÇ¥ in the
Ruby community is to put ‹BeginEndStorage› in a file called
‹begin_end_storage.rb›, I only name constants using a single noun. This
has had the added benefit that classes seem to have acquired less behavior,
as using a single noun doesnΓÇÖt allow you to tack on additional behavior
without questioning if itΓÇÖs really appropriate to do so, given the rather
limited range of interpretation for that noun. It also seems to encourage
the creation of value objects, as something named ‹Range› feels a lot more
like a value than ‹BeginEndStorage›. (To reach object-oriented-programming
Nirvana you must achieve complete value.)
§ News
§ 3.0.0
The ‹xml› expectation has been dropped. It wasn’t documented, didn’t
suit very many use cases, and can be better implemented by an external
library.
The ‹arg› argument matcher for mock method arguments has been removed, as
it didnΓÇÖt provide any benefit over using Object.
The ‹#yield› and ‹#each› methods on stub and mock methods have been
removed. They were slightly weird and their use case can be implemented
using block parameters instead.
The ‹stub› method inside ‹expect› blocks now stubs out the methods during
the execution of a provided block instead of during the execution of the
whole except block.
When a mock method is called too many times, this is reported
immediately, with a full backtrace. This makes it easier to pin down
whatΓÇÖs wrong with the code.
Query expectations were added.
Explicit query expectations were added.
Fluent boolean expectations, for example, ‹expect nil.to.be.nil?› have
been replaced by query expectations (‹expect :nil? do nil end›) and
explicit query expectations (‹expect result.to.be.nil? do nil end›).
This was done to discourage creating objects as the expected value and
creating objects that change during the course of the test.
The ‹literal› expectation was added.
Equality (‹#==›) is now checked before “caseity” (‹#===›) for modules,
ranges, and regular expressions to match the documentation.
§ Financing
Currently, most of my time is spent at my day job and in my rather busy
private life. Please motivate me to spend time on this piece of software
by donating some of your money to this project. Yeah, I realize that
requesting money to develop software is a bit, well, capitalistic of me.
But please realize that I live in a capitalistic society and I need money
to have other people give me the things that I need to continue living
under the rules of said society. So, if you feel that this piece of
software has helped you out enough to warrant a reward, please PayPal a
donation to now@disu.se┬╣. Thanks! Your support wonΓÇÖt go unnoticed!
┬╣ Send a donation:
https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=now%40disu%2ese&item_name=Lookout
§ Reporting Bugs
Please report any bugs that you encounter to the {issue tracker}┬╣.
┬╣ See https://github.com/now/lookout/issues
§ Contributors
Contributors to the original expectations codebase are mentioned there. We
hope no one on that list feels left out of this list. Please
{let us know}┬╣ if you do.
ΓÇó Nikolai Weibull
┬╣ Add an issue to the Lookout issue tracker at https://github.com/now/lookout/issues
§ Licensing
Lookout is free software: you may redistribute it and/or modify it under
the terms of the {GNU Lesser General Public License, version 3}┬╣ or later┬▓,
as published by the {Free Software Foundation}┬│.
┬╣ See http://disu.se/licenses/lgpl-3.0/
┬▓ See http://gnu.org/licenses/
┬│ See http://fsf.org/
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
Activity
0.0
The Tripletex API is a **RESTful API**, which does not implement PATCH, but uses a PUT with optional fields. **Actions** or commands are represented in our RESTful path with a prefixed `:`. Example: `/v2/hours/123/:approve`. **Summaries** or aggregated results are represented in our RESTful path with a prefixed <code>></code>. Example: <code>/v2/hours/>thisWeeksBillables</code>. **"requestID"** is a key found in all validation and error responses. If additional log information is absolutely necessary, our support division can locate the key value. **Download** the [swagger.json](/v2/swagger.json) file [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) to [generate code](https://github.com/sveredyuk/tripletex_ruby). This document was generated from the Swagger JSON file. **version:** This is a versioning number found on all DB records. If included, it will prevent your PUT/POST from overriding any updates to the record since your GET. **Date & DateTime** follows the **ISO 8601** standard. Date: `YYYY-MM-DD`. DateTime: `YYYY-MM-DDThh:mm:ssZ` **Sorting** is done by specifying a comma separated list, where a `-` prefix denotes descending. You can sort by sub object with the following format: `project.name, -date`. **Searching:** is done by entering values in the optional fields for each API call. The values fall into the following categories: range, in, exact and like. **Missing fields or even no response data** can occur because result objects and fields are filtered on authorization. **See [FAQ](https://tripletex.no/execute/docViewer?articleId=906&language=0) for more additional information.** ## Authentication: - **Tokens:** The Tripletex API uses 3 different tokens - **consumerToken**, **employeeToken** and **sessionToken**. - **consumerToken** is a token provided to the consumer by Tripletex after the API 2.0 registration is completed. - **employeeToken** is a token created by an administrator in your Tripletex account via the user settings and the tab "API access". Each employee token must be given a set of entitlements. [Read more here.](https://tripletex.no/execute/docViewer?articleId=853&language=0) - **sessionToken** is the token from `/token/session/:create` which requires a consumerToken and an employeeToken created with the same consumer token, but not an authentication header. See how to create a sessionToken [here](https://tripletex.no/execute/docViewer?articleId=855&language=0). - The session token is used as the password in "Basic Authentication Header" for API calls. - Use blank or `0` as username for accessing the account with regular employee token, or if a company owned employee token accesses <code>/company/>withLoginAccess</code> or <code>/token/session/>whoAmI</code>. - For company owned employee tokens (accounting offices) the ID from <code>/company/>withLoginAccess</code> can be used as username for accessing client accounts. - If you need to create the header yourself use <code>Authorization: Basic <base64encode('0:sessionToken')></code>. ## Tags: - <div class="tag-icon-beta"></div> **[BETA]** This is a beta endpoint and can be subject to change. - <div class="tag-icon-deprecated"></div> **[DEPRECATED]** Deprecated means that we intend to remove/change this feature or capability in a future "major" API release. We therefore discourage all use of this feature/capability. ## Fields: Use the `fields` parameter to specify which fields should be returned. This also supports fields from sub elements. Example values: - `project,activity,hours` returns `{project:..., activity:...., hours:...}`. - just `project` returns `"project" : { "id": 12345, "url": "tripletex.no/v2/projects/12345" }`. - `project(*)` returns `"project" : { "id": 12345 "name":"ProjectName" "number.....startDate": "2013-01-07" }`. - `project(name)` returns `"project" : { "name":"ProjectName" }`. - All elements and some subElements : `*,activity(name),employee(*)`. ## Changes: To get the changes for a resource, `changes` have to be explicitly specified as part of the `fields` parameter, e.g. `*,changes`. There are currently two types of change available: - `CREATE` for when the resource was created - `UPDATE` for when the resource was updated NOTE: For objects created prior to October 24th 2018 the list may be incomplete, but will always contain the CREATE and the last change (if the object has been changed after creation). ## Rate limiting in each response header: Rate limiting is performed on the API calls for an employee for each API consumer. Status regarding the rate limit is returned as headers: - `X-Rate-Limit-Limit` - The number of allowed requests in the current period. - `X-Rate-Limit-Remaining` - The number of remaining requests. - `X-Rate-Limit-Reset` - The number of seconds left in the current period. Once the rate limit is hit, all requests will return HTTP status code `429` for the remainder of the current period. ## Response envelope: ``` { "fullResultSize": ###, "from": ###, // Paging starting from "count": ###, // Paging count "versionDigest": "Hash of full result", "values": [...list of objects...] } { "value": {...single object...} } ``` ## WebHook envelope: ``` { "subscriptionId": ###, "event": "object.verb", // As listed from /v2/event/ "id": ###, // Object id "value": {... single object, null if object.deleted ...} } ``` ## Error/warning envelope: ``` { "status": ###, // HTTP status code "code": #####, // internal status code of event "message": "Basic feedback message in your language", "link": "Link to doc", "developerMessage": "More technical message", "validationMessages": [ // Will be null if Error { "field": "Name of field", "message": "Validation failure information" } ], "requestId": "UUID used in any logs" } ``` ## Status codes / Error codes: - **200 OK** - **201 Created** - From POSTs that create something new. - **204 No Content** - When there is no answer, ex: "/:anAction" or DELETE. - **400 Bad request** - - **4000** Bad Request Exception - **11000** Illegal Filter Exception - **12000** Path Param Exception - **24000** Cryptography Exception - **401 Unauthorized** - When authentication is required and has failed or has not yet been provided - **3000** Authentication Exception - **9000** Security Exception - **403 Forbidden** - When AuthorisationManager says no. - **404 Not Found** - For content/IDs that does not exist. - **6000** Not Found Exception - **409 Conflict** - Such as an edit conflict between multiple simultaneous updates - **7000** Object Exists Exception - **8000** Revision Exception - **10000** Locked Exception - **14000** Duplicate entry - **422 Bad Request** - For Required fields or things like malformed payload. - **15000** Value Validation Exception - **16000** Mapping Exception - **17000** Sorting Exception - **18000** Validation Exception - **21000** Param Exception - **22000** Invalid JSON Exception - **23000** Result Set Too Large Exception - **429 Too Many Requests** - Request rate limit hit - **500 Internal Error** - Unexpected condition was encountered and no more specific message is suitable - **1000** Exception
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
Activity
0.0
# Overview This guide documents the InsightVM Application Programming Interface (API) Version 3. This API supports the Representation State Transfer (REST) design pattern. Unless noted otherwise this API accepts and produces the `application/json` media type. This API uses Hypermedia as the Engine of Application State (HATEOAS) and is hypermedia friendly. All API connections must be made to the security console using HTTPS. ## Versioning Versioning is specified in the URL and the base path of this API is: `https://<host>:<port>/api/3/`. ## Specification An <a target="_blank" href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md">OpenAPI v2</a> specification (also known as Swagger 2) of this API is available. Tools such as <a target="_blank" href="https://github.com/swagger-api/swagger-codegen">swagger-codegen</a> can be used to generate an API client in the language of your choosing using this specification document. <p class="openapi">Download the specification: <a class="openapi-button" target="_blank" download="" href="/api/3/json"> Download </a></p> ## Authentication Authorization to the API uses HTTP Basic Authorization (see <a target="_blank" href="https://www.ietf.org/rfc/rfc2617.txt">RFC 2617</a> for more information). Requests must supply authorization credentials in the `Authorization` header using a Base64 encoded hash of `"username:password"`. <!-- ReDoc-Inject: <security-definitions> --> ### 2FA This API supports two-factor authentication (2FA) by supplying an authentication token in addition to the Basic Authorization. The token is specified using the `Token` request header. To leverage two-factor authentication, this must be enabled on the console and be configured for the account accessing the API. ## Resources ### Naming Resource names represent nouns and identify the entity being manipulated or accessed. All collection resources are pluralized to indicate to the client they are interacting with a collection of multiple resources of the same type. Singular resource names are used when there exists only one resource available to interact with. The following naming conventions are used by this API: | Type | Case | | --------------------------------------------- | ------------------------ | | Resource names | `lower_snake_case` | | Header, body, and query parameters parameters | `camelCase` | | JSON fields and property names | `camelCase` | #### Collections A collection resource is a parent resource for instance resources, but can itself be retrieved and operated on independently. Collection resources use a pluralized resource name. The resource path for collection resources follow the convention: ``` /api/3/{resource_name} ``` #### Instances An instance resource is a "leaf" level resource that may be retrieved, optionally nested within a collection resource. Instance resources are usually retrievable with opaque identifiers. The resource path for instance resources follows the convention: ``` /api/3/{resource_name}/{instance_id}... ``` ## Verbs The following HTTP operations are supported throughout this API. The general usage of the operation and both its failure and success status codes are outlined below. | Verb | Usage | Success | Failure | | --------- | ------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- | | `GET` | Used to retrieve a resource by identifier, or a collection of resources by type. | `200` | `400`, `401`, `402`, `404`, `405`, `408`, `410`, `415`, `500` | | `POST` | Creates a resource with an application-specified identifier. | `201` | `400`, `401`, `404`, `405`, `408`, `413`, `415`, `500` | | `POST` | Performs a request to queue an asynchronous job. | `202` | `400`, `401`, `405`, `408`, `410`, `413`, `415`, `500` | | `PUT` | Creates a resource with a client-specified identifier. | `200` | `400`, `401`, `403`, `405`, `408`, `410`, `413`, `415`, `500` | | `PUT` | Performs a full update of a resource with a specified identifier. | `201` | `400`, `401`, `403`, `405`, `408`, `410`, `413`, `415`, `500` | | `DELETE` | Deletes a resource by identifier or an entire collection of resources. | `204` | `400`, `401`, `405`, `408`, `410`, `413`, `415`, `500` | | `OPTIONS` | Requests what operations are available on a resource. | `200` | `401`, `404`, `405`, `408`, `500` | ### Common Operations #### OPTIONS All resources respond to the `OPTIONS` request, which allows discoverability of available operations that are supported. The `OPTIONS` response returns the acceptable HTTP operations on that resource within the `Allow` header. The response is always a `200 OK` status. ### Collection Resources Collection resources can support the `GET`, `POST`, `PUT`, and `DELETE` operations. #### GET The `GET` operation invoked on a collection resource indicates a request to retrieve all, or some, of the entities contained within the collection. This also includes the optional capability to filter or search resources during the request. The response from a collection listing is a paginated document. See [hypermedia links](#section/Overview/Paging) for more information. #### POST The `POST` is a non-idempotent operation that allows for the creation of a new resource when the resource identifier is not provided by the system during the creation operation (i.e. the Security Console generates the identifier). The content of the `POST` request is sent in the request body. The response to a successful `POST` request should be a `201 CREATED` with a valid `Location` header field set to the URI that can be used to access to the newly created resource. The `POST` to a collection resource can also be used to interact with asynchronous resources. In this situation, instead of a `201 CREATED` response, the `202 ACCEPTED` response indicates that processing of the request is not fully complete but has been accepted for future processing. This request will respond similarly with a `Location` header with link to the job-oriented asynchronous resource that was created and/or queued. #### PUT The `PUT` is an idempotent operation that either performs a create with user-supplied identity, or a full replace or update of a resource by a known identifier. The response to a `PUT` operation to create an entity is a `201 Created` with a valid `Location` header field set to the URI that can be used to access to the newly created resource. `PUT` on a collection resource replaces all values in the collection. The typical response to a `PUT` operation that updates an entity is hypermedia links, which may link to related resources caused by the side-effects of the changes performed. #### DELETE The `DELETE` is an idempotent operation that physically deletes a resource, or removes an association between resources. The typical response to a `DELETE` operation is hypermedia links, which may link to related resources caused by the side-effects of the changes performed. ### Instance Resources Instance resources can support the `GET`, `PUT`, `POST`, `PATCH` and `DELETE` operations. #### GET Retrieves the details of a specific resource by its identifier. The details retrieved can be controlled through property selection and property views. The content of the resource is returned within the body of the response in the acceptable media type. #### PUT Allows for and idempotent "full update" (complete replacement) on a specific resource. If the resource does not exist, it will be created; if it does exist, it is completely overwritten. Any omitted properties in the request are assumed to be undefined/null. For "partial updates" use `POST` or `PATCH` instead. The content of the `PUT` request is sent in the request body. The identifier of the resource is specified within the URL (not the request body). The response to a successful `PUT` request is a `201 CREATED` to represent the created status, with a valid `Location` header field set to the URI that can be used to access to the newly created (or fully replaced) resource. #### POST Performs a non-idempotent creation of a new resource. The `POST` of an instance resource most commonly occurs with the use of nested resources (e.g. searching on a parent collection resource). The response to a `POST` of an instance resource is typically a `200 OK` if the resource is non-persistent, and a `201 CREATED` if there is a resource created/persisted as a result of the operation. This varies by endpoint. #### PATCH The `PATCH` operation is used to perform a partial update of a resource. `PATCH` is a non-idempotent operation that enforces an atomic mutation of a resource. Only the properties specified in the request are to be overwritten on the resource it is applied to. If a property is missing, it is assumed to not have changed. #### DELETE Permanently removes the individual resource from the system. If the resource is an association between resources, only the association is removed, not the resources themselves. A successful deletion of the resource should return `204 NO CONTENT` with no response body. This operation is not fully idempotent, as follow-up requests to delete a non-existent resource should return a `404 NOT FOUND`. ## Requests Unless otherwise indicated, the default request body media type is `application/json`. ### Headers Commonly used request headers include: | Header | Example | Purpose | | ------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `Accept` | `application/json` | Defines what acceptable content types are allowed by the client. For all types, use `*/*`. | | `Accept-Encoding` | `deflate, gzip` | Allows for the encoding to be specified (such as gzip). | | `Accept-Language` | `en-US` | Indicates to the server the client's locale (defaults `en-US`). | | `Authorization ` | `Basic Base64("username:password")` | Basic authentication | | `Token ` | `123456` | Two-factor authentication token (if enabled) | ### Dates & Times Dates and/or times are specified as strings in the ISO 8601 format(s). The following formats are supported as input: | Value | Format | Notes | | --------------------------- | ------------------------------------------------------ | ----------------------------------------------------- | | Date | YYYY-MM-DD | Defaults to 12 am UTC (if used for a date & time | | Date & time only | YYYY-MM-DD'T'hh:mm:ss[.nnn] | Defaults to UTC | | Date & time in UTC | YYYY-MM-DD'T'hh:mm:ss[.nnn]Z | | | Date & time w/ offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm | | | Date & time w/ zone-offset | YYYY-MM-DD'T'hh:mm:ss[.nnn][+|-]hh:mm[<zone-id>] | | ### Timezones Timezones are specified in the regional zone format, such as `"America/Los_Angeles"`, `"Asia/Tokyo"`, or `"GMT"`. ### Paging Pagination is supported on certain collection resources using a combination of two query parameters, `page` and `size`. As these are control parameters, they are prefixed with the underscore character. The page parameter dictates the zero-based index of the page to retrieve, and the `size` indicates the size of the page. For example, `/resources?page=2&size=10` will return page 3, with 10 records per page, giving results 21-30. The maximum page size for a request is 500. ### Sorting Sorting is supported on paginated resources with the `sort` query parameter(s). The sort query parameter(s) supports identifying a single or multi-property sort with a single or multi-direction output. The format of the parameter is: ``` sort=property[,ASC|DESC]... ``` Therefore, the request `/resources?sort=name,title,DESC` would return the results sorted by the name and title descending, in that order. The sort directions are either ascending `ASC` or descending `DESC`. With single-order sorting, all properties are sorted in the same direction. To sort the results with varying orders by property, multiple sort parameters are passed. For example, the request `/resources?sort=name,ASC&sort=title,DESC` would sort by name ascending and title descending, in that order. ## Responses The following response statuses may be returned by this API. | Status | Meaning | Usage | | ------ | ------------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | OK | The operation performed without error according to the specification of the request, and no more specific 2xx code is suitable. | | `201` | Created | A create request has been fulfilled and a resource has been created. The resource is available as the URI specified in the response, including the `Location` header. | | `202` | Accepted | An asynchronous task has been accepted, but not guaranteed, to be processed in the future. | | `400` | Bad Request | The request was invalid or cannot be otherwise served. The request is not likely to succeed in the future without modifications. | | `401` | Unauthorized | The user is unauthorized to perform the operation requested, or does not maintain permissions to perform the operation on the resource specified. | | `403` | Forbidden | The resource exists to which the user has access, but the operating requested is not permitted. | | `404` | Not Found | The resource specified could not be located, does not exist, or an unauthenticated client does not have permissions to a resource. | | `405` | Method Not Allowed | The operations may not be performed on the specific resource. Allowed operations are returned and may be performed on the resource. | | `408` | Request Timeout | The client has failed to complete a request in a timely manner and the request has been discarded. | | `413` | Request Entity Too Large | The request being provided is too large for the server to accept processing. | | `415` | Unsupported Media Type | The media type is not supported for the requested resource. | | `500` | Internal Server Error | An internal and unexpected error has occurred on the server at no fault of the client. | ### Security The response statuses 401, 403 and 404 need special consideration for security purposes. As necessary, error statuses and messages may be obscured to strengthen security and prevent information exposure. The following is a guideline for privileged resource response statuses: | Use Case | Access | Resource | Permission | Status | | ------------------------------------------------------------------ | ------------------ |------------------- | ------------ | ------------ | | Unauthenticated access to an unauthenticated resource. | Unauthenticated | Unauthenticated | Yes | `20x` | | Unauthenticated access to an authenticated resource. | Unauthenticated | Authenticated | No | `401` | | Unauthenticated access to an authenticated resource. | Unauthenticated | Non-existent | No | `401` | | Authenticated access to a unauthenticated resource. | Authenticated | Unauthenticated | Yes | `20x` | | Authenticated access to an authenticated, unprivileged resource. | Authenticated | Authenticated | No | `404` | | Authenticated access to an authenticated, privileged resource. | Authenticated | Authenticated | Yes | `20x` | | Authenticated access to an authenticated, non-existent resource | Authenticated | Non-existent | Yes | `404` | ### Headers Commonly used response headers include: | Header | Example | Purpose | | -------------------------- | --------------------------------- | --------------------------------------------------------------- | | `Allow` | `OPTIONS, GET` | Defines the allowable HTTP operations on a resource. | | `Cache-Control` | `no-store, must-revalidate` | Disables caching of resources (as they are all dynamic). | | `Content-Encoding` | `gzip` | The encoding of the response body (if any). | | `Location` | | Refers to the URI of the resource created by a request. | | `Transfer-Encoding` | `chunked` | Specified the encoding used to transform response. | | `Retry-After` | 5000 | Indicates the time to wait before retrying a request. | | `X-Content-Type-Options` | `nosniff` | Disables MIME type sniffing. | | `X-XSS-Protection` | `1; mode=block` | Enables XSS filter protection. | | `X-Frame-Options` | `SAMEORIGIN` | Prevents rendering in a frame from a different origin. | | `X-UA-Compatible` | `IE=edge,chrome=1` | Specifies the browser mode to render in. | ### Format When `application/json` is returned in the response body it is always pretty-printed (indented, human readable output). Additionally, gzip compression/encoding is supported on all responses. #### Dates & Times Dates or times are returned as strings in the ISO 8601 'extended' format. When a date and time is returned (instant) the value is converted to UTC. For example: | Value | Format | Example | | --------------- | ------------------------------ | --------------------- | | Date | `YYYY-MM-DD` | 2017-12-03 | | Date & Time | `YYYY-MM-DD'T'hh:mm:ss[.nnn]Z` | 2017-12-03T10:15:30Z | #### Content In some resources a Content data type is used. This allows for multiple formats of representation to be returned within resource, specifically `"html"` and `"text"`. The `"text"` property returns a flattened representation suitable for output in textual displays. The `"html"` property returns an HTML fragment suitable for display within an HTML element. Note, the HTML returned is not a valid stand-alone HTML document. #### Paging The response to a paginated request follows the format: ```json { resources": [ ... ], "page": { "number" : ..., "size" : ..., "totalResources" : ..., "totalPages" : ... }, "links": [ "first" : { "href" : "..." }, "prev" : { "href" : "..." }, "self" : { "href" : "..." }, "next" : { "href" : "..." }, "last" : { "href" : "..." } ] } ``` The `resources` property is an array of the resources being retrieved from the endpoint, each which should contain at minimum a "self" relation hypermedia link. The `page` property outlines the details of the current page and total possible pages. The object for the page includes the following properties: - number - The page number (zero-based) of the page returned. - size - The size of the pages, which is less than or equal to the maximum page size. - totalResources - The total amount of resources available across all pages. - totalPages - The total amount of pages. The last property of the paged response is the `links` array, which contains all available hypermedia links. For paginated responses, the "self", "next", "previous", "first", and "last" links are returned. The "self" link must always be returned and should contain a link to allow the client to replicate the original request against the collection resource in an identical manner to that in which it was invoked. The "next" and "previous" links are present if either or both there exists a previous or next page, respectively. The "next" and "previous" links have hrefs that allow "natural movement" to the next page, that is all parameters required to move the next page are provided in the link. The "first" and "last" links provide references to the first and last pages respectively. Requests outside the boundaries of the pageable will result in a `404 NOT FOUND`. Paginated requests do not provide a "stateful cursor" to the client, nor does it need to provide a read consistent view. Records in adjacent pages may change while pagination is being traversed, and the total number of pages and resources may change between requests within the same filtered/queries resource collection. #### Property Views The "depth" of the response of a resource can be configured using a "view". All endpoints supports two views that can tune the extent of the information returned in the resource. The supported views are `summary` and `details` (the default). View are specified using a query parameter, in this format: ```bash /<resource>?view={viewName} ``` #### Error Any error responses can provide a response body with a message to the client indicating more information (if applicable) to aid debugging of the error. All 40x and 50x responses will return an error response in the body. The format of the response is as follows: ```json { "status": <statusCode>, "message": <message>, "links" : [ { "rel" : "...", "href" : "..." } ] } ``` The `status` property is the same as the HTTP status returned in the response, to ease client parsing. The message property is a localized message in the request client's locale (if applicable) that articulates the nature of the error. The last property is the `links` property. This may contain additional [hypermedia links](#section/Overview/Authentication) to troubleshoot. #### Search Criteria <a section="section/Responses/SearchCriteria"></a> Multiple resources make use of search criteria to match assets. Search criteria is an array of search filters. Each search filter has a generic format of: ```json { "field": "<field-name>", "operator": "<operator>", ["value": "<value>",] ["lower": "<value>",] ["upper": "<value>"] } ``` Every filter defines two required properties `field` and `operator`. The field is the name of an asset property that is being filtered on. The operator is a type and property-specific operating performed on the filtered property. The valid values for fields and operators are outlined in the table below. Every filter also defines one or more values that are supplied to the operator. The valid values vary by operator and are outlined below. ##### Fields The following table outlines the search criteria fields and the available operators: | Field | Operators | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `alternate-address-type` | `in` | | `container-image` | `is` ` is-not` ` starts-with` ` ends-with` ` contains` ` does-not-contain` ` is-like` ` not-like` | | `container-status` | `is` ` is-not` | | `containers` | `are` | | `criticality-tag` | `is` ` is-not` ` is-greater-than` ` is-less-than` ` is-applied` ` is-not-applied` | | `custom-tag` | `is` ` is-not` ` starts-with` ` ends-with` ` contains` ` does-not-contain` ` is-applied` ` is-not-applied` | | `cve` | `is` ` is-not` ` contains` ` does-not-contain` | | `cvss-access-complexity` | `is` ` is-not` | | `cvss-authentication-required` | `is` ` is-not` | | `cvss-access-vector` | `is` ` is-not` | | `cvss-availability-impact` | `is` ` is-not` | | `cvss-confidentiality-impact` | `is` ` is-not` | | `cvss-integrity-impact` | `is` ` is-not` | | `cvss-v3-confidentiality-impact` | `is` ` is-not` | | `cvss-v3-integrity-impact` | `is` ` is-not` | | `cvss-v3-availability-impact` | `is` ` is-not` | | `cvss-v3-attack-vector` | `is` ` is-not` | | `cvss-v3-attack-complexity` | `is` ` is-not` | | `cvss-v3-user-interaction` | `is` ` is-not` | | `cvss-v3-privileges-required` | `is` ` is-not` | | `host-name` | `is` ` is-not` ` starts-with` ` ends-with` ` contains` ` does-not-contain` ` is-empty` ` is-not-empty` ` is-like` ` not-like` | | `host-type` | `in` ` not-in` | | `ip-address` | `is` ` is-not` ` in-range` ` not-in-range` ` is-like` ` not-like` | | `ip-address-type` | `in` ` not-in` | | `last-scan-date` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` | | `location-tag` | `is` ` is-not` ` starts-with` ` ends-with` ` contains` ` does-not-contain` ` is-applied` ` is-not-applied` | | `mobile-device-last-sync-time` | `is-within-the-last` ` is-earlier-than` | | `open-ports` | `is` ` is-not` ` in-range` | | `operating-system` | `contains` ` does-not-contain` ` is-empty` ` is-not-empty` | | `owner-tag` | `is` ` is-not` ` starts-with` ` ends-with` ` contains` ` does-not-contain` ` is-applied` ` is-not-applied` | | `pci-compliance` | `is` | | `risk-score` | `is` ` is-not` ` in-range` ` greater-than` ` less-than` | | `service-name` | `contains` ` does-not-contain` | | `site-id` | `in` ` not-in` | | `software` | `contains` ` does-not-contain` | | `vAsset-cluster` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | | `vAsset-datacenter` | `is` ` is-not` | | `vAsset-host-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | | `vAsset-power-state` | `in` ` not-in` | | `vAsset-resource-pool-path` | `contains` ` does-not-contain` | | `vulnerability-assessed` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` | | `vulnerability-category` | `is` ` is-not` ` starts-with` ` ends-with` ` contains` ` does-not-contain` | | `vulnerability-cvss-v3-score` | `is` ` is-not` | | `vulnerability-cvss-score` | `is` ` is-not` ` in-range` ` is-greater-than` ` is-less-than` | | `vulnerability-exposures` | `includes` ` does-not-include` | | `vulnerability-title` | `contains` ` does-not-contain` ` is` ` is-not` ` starts-with` ` ends-with` | | `vulnerability-validated-status` | `are` | ##### Enumerated Properties The following fields have enumerated values: | Field | Acceptable Values | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `alternate-address-type` | 0=IPv4, 1=IPv6 | | `containers` | 0=present, 1=not present | | `container-status` | `created` `running` `paused` `restarting` `exited` `dead` `unknown` | | `cvss-access-complexity` | <ul><li><code>L</code> = Low</li><li><code>M</code> = Medium</li><li><code>H</code> = High</li></ul> | | `cvss-integrity-impact` | <ul><li><code>N</code> = None</li><li><code>P</code> = Partial</li><li><code>C</code> = Complete</li></ul> | | `cvss-confidentiality-impact` | <ul><li><code>N</code> = None</li><li><code>P</code> = Partial</li><li><code>C</code> = Complete</li></ul> | | `cvss-availability-impact` | <ul><li><code>N</code> = None</li><li><code>P</code> = Partial</li><li><code>C</code> = Complete</li></ul> | | `cvss-access-vector` | <ul><li><code>L</code> = Local</li><li><code>A</code> = Adjacent</li><li><code>N</code> = Network</li></ul> | | `cvss-authentication-required` | <ul><li><code>N</code> = None</li><li><code>S</code> = Single</li><li><code>M</code> = Multiple</li></ul> | | `cvss-v3-confidentiality-impact` | <ul><li><code>L</code> = Local</li><li><code>L</code> = Low</li><li><code>N</code> = None</li><li><code>H</code> = High</li></ul> | | `cvss-v3-integrity-impact` | <ul><li><code>L</code> = Local</li><li><code>L</code> = Low</li><li><code>N</code> = None</li><li><code>H</code> = High</li></ul> | | `cvss-v3-availability-impact` | <ul><li><code>N</code> = None</li><li><code>L</code> = Low</li><li><code>H</code> = High</li></ul> | | `cvss-v3-attack-vector` | <ul><li><code>N</code> = Network</li><li><code>A</code> = Adjacent</li><li><code>L</code> = Local</li><li><code>P</code> = Physical</li></ul> | | `cvss-v3-attack-complexity` | <ul><li><code>L</code> = Low</li><li><code>H</code> = High</li></ul> | | `cvss-v3-user-interaction` | <ul><li><code>N</code> = None</li><li><code>R</code> = Required</li></ul> | | `cvss-v3-privileges-required` | <ul><li><code>N</code> = None</li><li><code>L</code> = Low</li><li><code>H</code> = High</li></ul> | | `host-type` | 0=Unknown, 1=Guest, 2=Hypervisor, 3=Physical, 4=Mobile | | `ip-address-type` | 0=IPv4, 1=IPv6 | | `pci-compliance` | 0=fail, 1=pass | | `vulnerability-validated-status` | 0=present, 1=not present | ##### Operator Properties <a section="section/Responses/SearchCriteria/OperatorProperties"></a> The following table outlines which properties are required for each operator and the appropriate data type(s): | Operator | `value` | `lower` | `upper` | | ----------------------|-----------------------|-----------------------|-----------------------| | `are` | `string` | | | | `contains` | `string` | | | | `does-not-contain` | `string` | | | | `ends with` | `string` | | | | `in` | `Array[ string ]` | | | | `in-range` | | `numeric` | `numeric` | | `includes` | `Array[ string ]` | | | | `is` | `string` | | | | `is-applied` | | | | | `is-between` | | `numeric` | `numeric` | | `is-earlier-than` | `numeric` | | | | `is-empty` | | | | | `is-greater-than` | `numeric` | | | | `is-on-or-after` | `string` (yyyy-MM-dd) | | | | `is-on-or-before` | `string` (yyyy-MM-dd) | | | | `is-not` | `string` | | | | `is-not-applied` | | | | | `is-not-empty` | | | | | `is-within-the-last` | `numeric` | | | | `less-than` | `string` | | | | `like` | `string` | | | | `not-contains` | `string` | | | | `not-in` | `Array[ string ]` | | | | `not-in-range` | | `numeric` | `numeric` | | `not-like` | `string` | | | | `starts-with` | `string` | | | #### Discovery Connection Search Criteria <a section="section/Responses/DiscoverySearchCriteria"></a> Dynamic sites make use of search criteria to match assets from a discovery connection. Search criteria is an array of search filters. Each search filter has a generic format of: ```json { "field": "<field-name>", "operator": "<operator>", ["value": "<value>",] ["lower": "<value>",] ["upper": "<value>"] } ``` Every filter defines two required properties `field` and `operator`. The field is the name of an asset property that is being filtered on. The list of supported fields vary depending on the type of discovery connection configured for the dynamic site (e.g vSphere, ActiveSync, etc.). The operator is a type and property-specific operating performed on the filtered property. The valid values for fields outlined in the tables below and are grouped by the type of connection. Every filter also defines one or more values that are supplied to the operator. See <a href="#section/Responses/SearchCriteria/OperatorProperties">Search Criteria Operator Properties</a> for more information on the valid values for each operator. ##### Fields (ActiveSync) This section documents search criteria information for ActiveSync discovery connections. The discovery connections must be one of the following types: `"activesync-ldap"`, `"activesync-office365"`, or `"activesync-powershell"`. The following table outlines the search criteria fields and the available operators for ActiveSync connections: | Field | Operators | | --------------------------------- | ------------------------------------------------------------- | | `last-sync-time` | `is-within-the-last` ` is-earlier-than` | | `operating-system` | `contains` ` does-not-contain` | | `user` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | ##### Fields (AWS) This section documents search criteria information for AWS discovery connections. The discovery connections must be the type `"aws"`. The following table outlines the search criteria fields and the available operators for AWS connections: | Field | Operators | | ----------------------- | ------------------------------------------------------------- | | `availability-zone` | `contains` ` does-not-contain` | | `guest-os-family` | `contains` ` does-not-contain` | | `instance-id` | `contains` ` does-not-contain` | | `instance-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | | `instance-state` | `in` ` not-in` | | `instance-type` | `in` ` not-in` | | `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` | | `region` | `in` ` not-in` | | `vpc-id` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | ##### Fields (DHCP) This section documents search criteria information for DHCP discovery connections. The discovery connections must be the type `"dhcp"`. The following table outlines the search criteria fields and the available operators for DHCP connections: | Field | Operators | | --------------- | ------------------------------------------------------------- | | `host-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | | `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` | | `mac-address` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | ##### Fields (Sonar) This section documents search criteria information for Sonar discovery connections. The discovery connections must be the type `"sonar"`. The following table outlines the search criteria fields and the available operators for Sonar connections: | Field | Operators | | ------------------- | -------------------- | | `search-domain` | `contains` ` is` | | `ip-address` | `in-range` ` is` | | `sonar-scan-date` | `is-within-the-last` | ##### Fields (vSphere) This section documents search criteria information for vSphere discovery connections. The discovery connections must be the type `"vsphere"`. The following table outlines the search criteria fields and the available operators for vSphere connections: | Field | Operators | | -------------------- | ------------------------------------------------------------------------------------------ | | `cluster` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | | `data-center` | `is` ` is-not` | | `discovered-time` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` | | `guest-os-family` | `contains` ` does-not-contain` | | `host-name` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | | `ip-address` | `in-range` ` not-in-range` ` is` ` is-not` | | `power-state` | `in` ` not-in` | | `resource-pool-path` | `contains` ` does-not-contain` | | `last-time-seen` | `is-on-or-before` ` is-on-or-after` ` is-between` ` is-earlier-than` ` is-within-the-last` | | `vm` | `is` ` is-not` ` contains` ` does-not-contain` ` starts-with` | ##### Enumerated Properties (vSphere) The following fields have enumerated values: | Field | Acceptable Values | | ------------- | ------------------------------------ | | `power-state` | `poweredOn` `poweredOff` `suspended` | ## HATEOAS This API follows Hypermedia as the Engine of Application State (HATEOAS) principals and is therefore hypermedia friendly. Hyperlinks are returned in the `links` property of any given resource and contain a fully-qualified hyperlink to the corresponding resource. The format of the hypermedia link adheres to both the <a target="_blank" href="http://jsonapi.org">{json:api} v1</a> <a target="_blank" href="http://jsonapi.org/format/#document-links">"Link Object"</a> and <a target="_blank" href="http://json-schema.org/latest/json-schema-hypermedia.html">JSON Hyper-Schema</a> <a target="_blank" href="http://json-schema.org/latest/json-schema-hypermedia.html#rfc.section.5.2">"Link Description Object"</a> formats. For example: ```json "links": [{ "rel": "<relation>", "href": "<href>" ... }] ``` Where appropriate link objects may also contain additional properties than the `rel` and `href` properties, such as `id`, `type`, etc. See the [Root](#tag/Root) resources for the entry points into API discovery.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
Releases
Activity
0.0
# Rake::ToolkitProgram
Create toolkit programs easily with `Rake` and `OptionParser` syntax. Bash completions and usage help are baked in.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'rake-toolkit_program'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install rake-toolkit_program
## Quickstart
* Shebang it up (in a file named `awesome_tool.rb`)
```ruby
#!/usr/bin/env ruby
```
* Require the library
```ruby
require 'rake/toolkit_program'
```
* Make your life easier
```ruby
Program = Rake::ToolkitProgram
```
* Define your command tasks
```ruby
Program.command_tasks do
desc "Build it"
task 'build' do
# Ruby code here
end
desc "Test it"
task 'test' => ['build'] do
# Rake syntax ↑↑↑↑↑↑↑ for dependencies
# Ruby code here
end
end
```
You can use `Program.args` in your tasks to access the other arguments on the command line. For argument parsing integrated into the help provided by the program, see the use of `Rake::Task(Rake::ToolkitProgram::TaskExt)#parse_args` below.
* Wire the mainline
```ruby
Program.run(on_error: :exit_program!) if $0 == __FILE__
```
* In the shell, prepare to run the program (UNIX/Linux systems only)
```console
$ chmod +x awesome_tool.rb
$ ./awesome_tool.rb --install-completions
Completions installed in /home/rtweeks/.bashrc
Source /home/rtweeks/.bash-complete/awesome_tool.rb-completions for immediate availability.
$ source /home/rtweeks/.bash-complete/awesome_tool.rb-completions
```
* Ask for help
```console
$ ./awesome_tool.rb help
*** ./awesome_tool.rb Toolkit Program ***
.
.
.
```
## Usage
Let's look at a short sample toolkit program -- put this in `awesome.rb`:
```ruby
#!/usr/bin/env ruby
require 'rake/toolkit_program'
require 'ostruct'
ToolkitProgram = Rake::ToolkitProgram
ToolkitProgram.title = "My Awesome Toolkit of Awesome"
ToolkitProgram.command_tasks do
desc <<-END_DESC.dedent
Fooing myself
I'm not sure what I'm doing, but I'm definitely fooing!
END_DESC
task :foo do
a = ToolkitProgram.args
puts "I'm fooed#{' on a ' if a.implement}#{a.implement}"
end.parse_args(into: OpenStruct.new) do |parser, args|
parser.no_positional_args!
parser.on('-i', '--implement IMPLEMENT', 'An implement on which to be fooed') do |val|
args.implement = val
end
end
end
if __FILE__ == $0
ToolkitProgram.run(on_error: :exit_program!)
end
```
Make sure to `chmod +x awesome.rb`!
What does this support?
$ ./awesome.rb foo
I'm fooed
$ ./awesome.rb --help
*** My Awesome Toolkit of Awesome ***
Usage: ./awesome.rb COMMAND [OPTION ...]
Avaliable options vary depending on the command given. For details
of a particular command, use:
./awesome.rb help COMMAND
Commands:
foo Fooing myself
help Show a list of commands or details of one command
Use help COMMAND to get more help on a specific command.
$ ./awesome.rb help foo
*** My Awesome Toolkit of Awesome ***
Usage: ./awesome.rb foo [OPTION ...]
Fooing myself
I'm not sure what I'm doing, but I'm definitely fooing!
Options:
-i, --implement IMPLEMENT An implement on which to be fooed
$ ./awesome.rb --install-completions
Completions installed in /home/rtweeks/.bashrc
Source /home/rtweeks/.bash-complete/awesome.rb-completions for immediate availability.
$ source /home/rtweeks/.bash-complete/awesome.rb-completions
$ ./awesome.rb <tab><tab>
foo help
$ ./awesome.rb f<tab>
↳ ./awesome.rb foo
$ ./awesome.rb foo <tab>
↳ ./awesome.rb foo --
$ ./awesome.rb foo --<tab><tab>
--help --implement
$ ./awesome.rb foo --i<tab>
↳ ./awesome.rb foo --implement
$ ./awesome.rb foo --implement <tab><tab>
--help awesome.rb
$ ./awesome.rb foo --implement spoon
I'm fooed on a spoon
### Defining Toolkit Commands
Just define tasks in the block of `Rake::ToolkitProgram.command_tasks` with `task` (i.e. `Rake::DSL#task`). If `desc` is used to provide a description, the task will become visible in help and completions.
When a command task is initially defined, positional arguments to the command are available as an `Array` through `Rake::ToolkitProgram.args`.
### Option Parsing
This gem extends `Rake::Task` with a `#parse_args` method that creates a `Rake::ToolkitProgram::CommandOptionParser` (derived from the standard library's `OptionParser`) and an argument accumulator and `yield`s them to its block.
* The arguments accumulated through the `Rake::ToolkitProgram::CommandOptionParser` are available to the task in `Rake::ToolkitProgram.args`, replacing the normal `Array` of positional arguments.
* Use the `into:` keyword of `#parse_args` to provide a custom argument accumulator object for the associated command. The default argument accumulator constructor can be defined with `Rake::ToolkitProgram.default_parsed_args`. Without either of these, the default accumulator is a `Hash`.
* Options defined using `OptionParser#on` (or any of the variants) will print in the help for the associated command.
### Positional Arguments
Accessing positional arguments given after the command name depends on whether or not `Rake::Task(Rake::ToolkitProgram::TaskExt)#parse_args` has been called on the command task. If this method is not called, positional arguments will be an `Array` accessible through `Rake::ToolkitProgram.args`.
When `Rake::Task(Rake::ToolkitProgram::TaskExt)#parse_args` is used:
* `Rake::ToolkitProgram::CommandOptionParser#capture_positionals` can be used to define how positional arguments are accumulated.
* If the argument accumulator is a `Hash`, the default (without calling this method) is to assign the `Array` of positional arguments to the `nil` key of the `Hash`.
* For other types of accumulators, the positional arguments are only accessible if `Rake::ToolkitProgram::CommandOptionParser#capture_positionals` is used to define how they are captured.
* If a block is given to this method, the block of the method will receive the `Array` of positional arguments. If it is passed an argument value, that value is used as the key under which to store the positional arguments if the argument accumulator is a `Hash`.
* `Rake::ToolkitProgram::CommandOptionParser#expect_positional_cardinality` can be used to set a rule for the count of positional arguments. This will affect the _usage_ presented in the help for the associated command.
* `Rake::ToolkitProgram::CommandOptionParser#map_positional_args` may be used to transform (or otherwise process) positional arguments one at a time and in the context of options and/or arguments appearing earlier on the command line.
### Convenience Methods
* `Rake::Task(Rake::ToolkitProgram::TaskExt)#prohibit_args` is a quick way, for commands that accept no options or positional arguments, to declare this so the help and bash completions reflect this. It is equivalent to using `#parse_args` and telling the parser `parser.expect_positional_cardinality(0)`.
* `Rake::ToolkitProgram::CommandOptionParser#no_positional_args!` is a shortcut for calling `#expect_positional_cardinality(0)` on the same object.
* `Rake::Task(Rake::ToolkitProgram::TaskExt)#invalid_args!` and `Rake::ToolkitProgram::CommandOptionParser#invalid_args!` are convenient ways to raise `Rake::ToolkitProgram::InvalidCommandLine` with a message.
## OptionParser in Rubies Before and After v2.4
The `OptionParser` class was extended in Ruby 2.4 to simplify capturing options into a `Hash` or other container implementing `#[]=` in a similar way. This gem supports that, but it means that behavior varies somewhat between the pre-2.4 era and the 2.4+ era. To have consistent behavior across that version change, the recommendation is to use a `Struct`, `OpenStruct`, or custom class to hold program options rather than `Hash`.
## Development
After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
To run the tests, use `rake`, `rake test`, or `rspec spec`. Tests can only be run on systems that support `Kernel#fork`, as this is used to present a pristine and isolated environment for setting up the tool. If run using Ruby 2.3 or earlier, some tests will be pending because functionality expects Ruby 2.4's `OptionParser`.
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/PayTrace/rake-toolkit_program. For further details on contributing, see [CONTRIBUTING.md](./CONTRIBUTING.md).
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
0.0
The Tripletex API is a **RESTful API**, which does not implement PATCH, but uses a PUT with optional fields. **Actions** or commands are represented in our RESTful path with a prefixed `:`. Example: `/v2/hours/123/:approve`. **Summaries** or aggregated results are represented in our RESTful path with a prefixed <code>></code>. Example: <code>/v2/hours/>thisWeeksBillables</code>. **"requestID"** is a key found in all validation and error responses. If additional log information is absolutely necessary, our support division can locate the key value. **Download** the [swagger.json](/v2/swagger.json) file [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) to [generate code](https://github.com/swagger-api/swagger-codegen). This document was generated from the Swagger JSON file. **version:** This is a versioning number found on all DB records. If included, it will prevent your PUT/POST from overriding any updates to the record since your GET. **Date & DateTime** follows the **ISO 8601** standard. Date: `YYYY-MM-DD`. DateTime: `YYYY-MM-DDThh:mm:ssZ` **Sorting** is done by specifying a comma separated list, where a `-` prefix denotes descending. You can sort by sub object with the following format: `project.name, -date`. **Searching:** is done by entering values in the optional fields for each API call. The values fall into the following categories: range, in, exact and like. **Missing fields or even no response data** can occur because result objects and fields are filtered on authorization. **See [FAQ](https://tripletex.no/execute/docViewer?articleId=906&language=0) for more additional information.** ## Authentication: - **Tokens:** The Tripletex API uses 3 different tokens - **consumerToken**, **employeeToken** and **sessionToken**. - **consumerToken** is a token provided to the consumer by Tripletex after the API 2.0 registration is completed. - **employeeToken** is a token created by an administrator in your Tripletex account via the user settings and the tab "API access". Each employee token must be given a set of entitlements. [Read more here.](https://tripletex.no/execute/docViewer?articleId=853&language=0) - **sessionToken** is the token from `/token/session/:create` which requires a consumerToken and an employeeToken created with the same consumer token, but not an authentication header. See how to create a sessionToken [here](https://tripletex.no/execute/docViewer?articleId=855&language=0). - The session token is used as the password in "Basic Authentication Header" for API calls. - Use blank or `0` as username for accessing the account with regular employee token, or if a company owned employee token accesses <code>/company/>withLoginAccess</code> or <code>/token/session/>whoAmI</code>. - For company owned employee tokens (accounting offices) the ID from <code>/company/>withLoginAccess</code> can be used as username for accessing client accounts. - If you need to create the header yourself use <code>Authorization: Basic <base64encode('0:sessionToken')></code>. ## Tags: - <div class="tag-icon-beta"></div> **[BETA]** This is a beta endpoint and can be subject to change. - <div class="tag-icon-deprecated"></div> **[DEPRECATED]** Deprecated means that we intend to remove/change this feature or capability in a future "major" API release. We therefore discourage all use of this feature/capability. ## Fields: Use the `fields` parameter to specify which fields should be returned. This also supports fields from sub elements. Example values: - `project,activity,hours` returns `{project:..., activity:...., hours:...}`. - just `project` returns `"project" : { "id": 12345, "url": "tripletex.no/v2/projects/12345" }`. - `project(*)` returns `"project" : { "id": 12345 "name":"ProjectName" "number.....startDate": "2013-01-07" }`. - `project(name)` returns `"project" : { "name":"ProjectName" }`. - All elements and some subElements : `*,activity(name),employee(*)`. ## Changes: To get the changes for a resource, `changes` have to be explicitly specified as part of the `fields` parameter, e.g. `*,changes`. There are currently two types of change available: - `CREATE` for when the resource was created - `UPDATE` for when the resource was updated NOTE: For objects created prior to October 24th 2018 the list may be incomplete, but will always contain the CREATE and the last change (if the object has been changed after creation). ## Rate limiting in each response header: Rate limiting is performed on the API calls for an employee for each API consumer. Status regarding the rate limit is returned as headers: - `X-Rate-Limit-Limit` - The number of allowed requests in the current period. - `X-Rate-Limit-Remaining` - The number of remaining requests. - `X-Rate-Limit-Reset` - The number of seconds left in the current period. Once the rate limit is hit, all requests will return HTTP status code `429` for the remainder of the current period. ## Response envelope: ``` { "fullResultSize": ###, "from": ###, // Paging starting from "count": ###, // Paging count "versionDigest": "Hash of full result", "values": [...list of objects...] } { "value": {...single object...} } ``` ## WebHook envelope: ``` { "subscriptionId": ###, "event": "object.verb", // As listed from /v2/event/ "id": ###, // Object id "value": {... single object, null if object.deleted ...} } ``` ## Error/warning envelope: ``` { "status": ###, // HTTP status code "code": #####, // internal status code of event "message": "Basic feedback message in your language", "link": "Link to doc", "developerMessage": "More technical message", "validationMessages": [ // Will be null if Error { "field": "Name of field", "message": "Validation failure information" } ], "requestId": "UUID used in any logs" } ``` ## Status codes / Error codes: - **200 OK** - **201 Created** - From POSTs that create something new. - **204 No Content** - When there is no answer, ex: "/:anAction" or DELETE. - **400 Bad request** - - **4000** Bad Request Exception - **11000** Illegal Filter Exception - **12000** Path Param Exception - **24000** Cryptography Exception - **401 Unauthorized** - When authentication is required and has failed or has not yet been provided - **3000** Authentication Exception - **9000** Security Exception - **403 Forbidden** - When AuthorisationManager says no. - **404 Not Found** - For content/IDs that does not exist. - **6000** Not Found Exception - **409 Conflict** - Such as an edit conflict between multiple simultaneous updates - **7000** Object Exists Exception - **8000** Revision Exception - **10000** Locked Exception - **14000** Duplicate entry - **422 Bad Request** - For Required fields or things like malformed payload. - **15000** Value Validation Exception - **16000** Mapping Exception - **17000** Sorting Exception - **18000** Validation Exception - **21000** Param Exception - **22000** Invalid JSON Exception - **23000** Result Set Too Large Exception - **429 Too Many Requests** - Request rate limit hit - **500 Internal Error** - Unexpected condition was encountered and no more specific message is suitable - **1000** Exception
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
Activity