Project

dsel

0.0
Low commit activity in last 3 years
DSL/API generator and runner.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies
 Project Readme

DSeL

You can use DSeL (pronounced Diesel -- best I could do) to:

  • Safely interact with any object as if you were operating within it.
    • No need to keep typing obj.* to work on obj.
  • Unsafely re-open (almost) any object like you re-open a Class and mess about it there.
  • Define clean APIs for 3rd party functionality via a DSL.
    • Documentation can be generated dynamically using API tree data.
  • Access APIs via a DSL.
    • Allows for scripting etc.
  • Create custom DSLs.

Currently an unstable work in progress, touch at own risk.

Description

It is:

  • A generic DSL (DSeL::DSL::Nodes::Base) supporting:
    • Proxy (DSeL::DSL::Nodes::Proxy) environments for safe interaction with any given object.
      • Method calls are forwarded.
      • Internal state not affected nor accessible.
    • Direct (DSeL::DSL::Nodes::Direct) environments, where the DSL context is the actual object instance.
    • Preserved contexts:
      • Re-entrant.
      • Re-usable.
      • Per object instance.
      • Shared variables across environment nodes.
      • Tree environment structure, with traversal helpers:
        • Root
        • Parent
  • An API specification framework (DSeL::API::Node).
    • Specify call:
      • Description
      • Type
      • Object/catch-call
      • Arguments and &block.
      • Handler
    • Tree structure for sections.
  • An API specification language (DSeL::DSL::APIBuilder).
    • import external API spec files.
    • Define and describe sections (children).
  • An API runner.
    • Providing a specialised DSL (DSeL::DSL::Nodes::API) for API nodes (DSeL::API::Node).

Installation

Add this line to your application's Gemfile:

gem 'dsel', github: 'qadron/dsel'

And then execute:

$ bundle

Examples

See: examples/

API

Include the API specification:

require_relative 'examples/api/my_api'

Use via a DSL script:

MyAPI.run 'examples/api/my_api_dsl.rb'

Use via a Ruby script:

require 'examples/api/my_api_ruby'

See: examples/api/

DSL

See: examples/dsl/object.rb

Proxy

The safe way to get a DSL is to run the object inside a Proxy context and just proxy methods, thus allowing the user to interact with the object as if operating within it semantically but without access to non-public methods or its state.

See: examples/dsl/proxy.rb

Direct

The direct way means not having the object inside the environment, but the environment inside the object, thus allowing you to truly operate within it and make a general mess of things or do some pretty cool stuff.

See: examples/dsl/direct.rb

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/qadron/dsel.

License

Please see the LICENSE.md file.