Topoisomerase
This gem aims to creates stubs for dynamic methods allowing static documentation tools (e.g YARD) and IDEs to parse the files and create linkages for these methods.
Inspiration
From wikipedia:
Topoisomerases are enzymes that participate in the overwinding or underwinding of DNA. The winding problem of DNA arises due to the intertwined nature of its double-helical structure. During DNA replication and transcription, DNA becomes overwound ahead of a replication fork.
The hope for this gem is to help document Ruby and unwind
gems, libraries for those learning to use them.
The gem page_object_stub
also inspired me of what could be done. I wanted to take things a step further to
make a more generic library.
Installation
Add this line to your application's Gemfile:
gem 'topoisomerase'
And then execute:
$ bundle
Or install it yourself as:
$ gem install topoisomerase
Usage
For one class
Before creating stubs, make sure that you require all the files that you want to create stubs for. Otherwise it will not create stubs for anything.
To create a stub file for a class, call the create_stubs_for
passing that class.
E.g:
Topoisomerase.create_stubs_for BasicClass
By default stubs will be created in the stubs
folder.
This can be changed by setting the stub_folder
variable.
Topoisomerase.stub_folder = 'custom_folder'
Note that this will by default attempt to instantiate the class with ClassName.new. If parameters are
needed pass a block to the create_stubs_for
as shown below. The result of the block will be the
instance of the class used in creating stubs.
Topoisomerase.create_stubs_for ParameterizedClass do
ParameterizedClass.new 5
end
For classes inheriting from another
To create stubs for all classes inheriting from a class or module use the create_stubs_based_on
method.
If the instantiation of such objects require parameters pass a parameter in the block to represent each class
that is found inheriting from the base class.
Eg:
Topoisomerase.create_stubs_based_on PageObject do |inheriting_class|
inheriting_class.new(:config_1, 'config 2')
end
Comments
If comments are used above a define_method
method then they will be used as comments above the stub generated from it
by default.
Otherwise the Topoisomerase::Comments
class can be used. The following shows hows to add comments when generating stubs
for all classes inheriting from / including the PageObject
module. It adds
Eg:
#
Topoisomerase::Comments.add_for_class PageObject do
comment "Set the '<%= method_to_stub.to_s.gsub('?', '') %>' text field",
method_name: /=$/, source: /text_field_value_set/
end
Notes
For efficiency and maintainability, it's recommended that the least needed to instantiate the class that will still generate the methods you need be used. However it may be just as easy to reuse the code you use when creating the objects themselves if it is generic enough.
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. 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.
Contributing
Bug reports and pull requests are welcome on GitLab at https://gitlab.com/samuel-garratt/topoisomerase. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Topoisomerase project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.