Repository files navigation

Sord is aSorbet andYARDcrossover. It canautomatically generate RBI and RBS type signature files bylooking at thetypes specified in YARD documentation comments.

If your project is already YARD documented, then this can generate most of thetype signatures you need!

Sord is the perfect way to jump-start the adoption of types in your project,whether you plan to use Sorbet's RBI format or Ruby 3/Steep's RBS format.

Try Sord online at:sord.aaronc.cc

Sord has the following features:

• Automatically generates signatures for modules, classes and methods
• Support for multiple parameter or return types (T.any/|)
• Gracefully handles missing YARD types (T.untyped/untyped)
• Can infer setter parameter type from the corresponding getter's return type
• Recognises mixins (include andextend)
• Support for generic types such asArray<T> andHash<K, V>
• Can infer namespaced classes ([Bar] can becomeGemName::Foo::Bar)
• Handles return types which can benil (T.nilable/untyped)
• Handles duck types (T.untyped/untyped)
• Support for ordered list types ([Array(Integer, Symbol)] becomes[Integer, Symbol])
• Support for boolean types ([true, false] becomesT::Boolean/bool)
• Support for&block parameters documented with@yieldparam and@yieldreturn

Install Sord withgem install sord.

Sord is a command line tool. To use it, open a terminal in the root directoryof your project and invokesord, passing a path where you'd like to save yourfile (this file will be overwritten):

sord defs.rbi

Sord will generate YARD docs and then print information about what it's inferredas it runs. It is best to fix any issues in the YARD documentation, as any editsmade to the resulting file will be replaced if you re-run Sord.

The output type is inferred by the file extension you use, but you can alsospecify it explicitly with--rbi or--rbs.

RBI files generated by Sord can be used in two main ways:

• Shipped in the gem itself.
• Contributed tosorbet-typed.

Generally, you should ship the type signatures with your gem if possible.sorbet-typed is meant to be a place for gems that are no longer updated orwhere the maintainer is unwilling to ship type signatures with the gem itself.

Sord also takes some flags to alter the generated file:

• --rbi/--rbs: Override the output format inferred from the fileextension.
• --no-sord-comments: Generates the file without any Sord comments aboutwarnings/inferences/errors. (The original file's comments will still beincluded.)
• --no-regenerate: By default, Sord will regenerate a repository's YARDdocs for you. This option skips regenerating the YARD docs.
• --break-params: Determines how many parameters are necessary beforethe signature is changed from a single-line to a multi-line block.(Default: 4)
• --replace-errors-with-untyped: UsesT.untyped instead ofSORD_ERROR_*constants.
• --replace-unresolved-with-untyped: UsesT.untyped when Sord is unable toresolve a constant.
• --include-messages and--exclude-messages: Used to filter the loggingmessages given by Sord.--include-messages acts as a whitelist, printingonly messages of the specified logging kinds, whereas--exclude-messagesacts as a blacklist and suppresses the specified logging kinds. Both flagstake a comma-separated list of logging kinds, for exampleomit,infer.When using--include-messages, thedone kind is included by default.(You cannot specify both--include-messages and--exclude-messages.)
• --exclude-untyped: Exclude methods and attributes with untyped returnvalues.
• --tags TAGS: Provide a list of comma-separated tags as understood by theyard command. E.g. `--tags 'mytag:My Description,mytag2:My New Description'

Say we have this file, calledtest.rb:

moduleExampleclassPerson# @param name [String] The name of the Person to create.# @param age [Integer] The age of the Person to create.# @return [Example::Person]definitialize(name,age)@name=name@age=ageend# @return [String]attr_accessor:name# @return [Integer]attr_accessor:age# @param possible_names [Array<String>] An array of potential names to choose from.# @param possible_ages [Array<Integer>] An array of potential ages to choose from.# @return [Example::Person]defself.construct_randomly(possible_names,possible_ages)Person.new(possible_names.sample,possible_ages.sample)endendend

First, generate a YARD registry by runningyardoc test.rb. Then, we can runsord test.rbi to generate the RBI file. (Careful not to overwrite your codefiles! Note the.rbi file extension.) In doing this, Sord prints:

[INFER] Assuming from filename you wish to generate in RBI format[DONE ] Processed 8 objects (2 namespaces and 6 methods)

Thetest.rbi file then contains a complete RBI file fortest.rb:

# typed: strongmoduleExampleclassPerson# _@param_ `name` — The name of the Person to create.## _@param_ `age` — The age of the Person to create.sig{params(name:String,age:Integer).void}definitialize(name,age);end# _@param_ `possible_names` — An array of potential names to choose from.## _@param_ `possible_ages` — An array of potential ages to choose from.sig{params(possible_names:T::Array[String],possible_ages:T::Array[Integer]).returns(Example::Person)}defself.construct_randomly(possible_names,possible_ages);endsig{returns(String)}attr_accessor:namesig{returns(Integer)}attr_accessor:ageendend

If we had instead generatedtest.rbs, we would get this file in RBS format:

moduleExampleclassPerson# _@param_ `name` — The name of the Person to create.## _@param_ `age` — The age of the Person to create.definitialize:(Stringname,Integerage) ->void# _@param_ `possible_names` — An array of potential names to choose from.## _@param_ `possible_ages` — An array of potential ages to choose from.defself.construct_randomly:(Array[String]possible_names,Array[Integer]possible_ages) ->Example::Personattr_accessorname:Stringattr_accessorage:Integerendend

The general rule of thumb for type conversions is:

• If Sord understands the YARD type, then it is converted into the RBI or RBStype.
• If the YARD type is missing, Sord fills inT.untyped.
• If the YARD type can't be understood, Sord creates an undefined Ruby constantwith a similar name to the unknown YARD type. For example, the obviouslyinvalid YARD typeA%B will become a constant calledSORD_ERROR_AB.You should search through your resulting file to find and fix andSORD_ERRORs.

Bug reports and pull requests are welcome on GitHub athttps://github.com/AaronC81/sord. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to theContributor Covenant code of conduct.

While contributing, if you want to see the results of your changes to Sord youcan use theexamples:seed Rake task. The task uses Sord to generate types fora number of open source Ruby gems, including Bundler, Haml, Rouge, and RSpec.rake examples:seed (andrake examples:reseed to regenerate the files) willclone the repositories of these gems intosord_examples/ and then generate thefiles into the same directory.

The gem is available as open source under the terms of theMIT License.

Everyone interacting in the Sord project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow thecode of conduct.