adjivas/ml

A library to generating UML language from Rust's project into graphiz/dot file.

ML -Modeling Language-

A library to generating UML language from Rust's project into graphiz/dot file.

Usage

This repo is provided as a Cargo package and a build script.

1. adjust your Cargo.toml to include.

build = "build.rs"

[build-dependencies.mml]
version = "0.1"

2. And your build.rs to generate your uml graph/viz and Structured Vector Graphics at target/dot/$CARGO_PKG_NAME.{dot,svg}.

extern crate mml;

fn main() {
    let dest: String = concat!("target/doc/", env!("CARGO_PKG_NAME")).to_string();

    let _ = mml::src2both("src", dest.replace("-", "_").as_str());
}

3. (Facultative) From your entry point library file, you can add the generated vectorized graph.

//! ![uml](ml.svg)

4. (Facultative) With the travis-cargo's instructions, you can prepare your graphviz's dependency like with this example.

addons:
  apt:
    packages:
      - graphviz
before_script:
  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew update           ; fi
  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew install graphviz ; fi
...
script:
  - |
      travis-cargo build &&
...

Features

Consider this list of fonctionalities like unstandard-uml.

• implem -- add a column to show the functions from a implementation.
• fn-emilgardis -- the function fields are preceded by fn keyword (Asked by Emilgardis).

Knowledge

This is a reading list of material relevant to Ml. It includes prior research that has - at one time or another - influenced the design of Ml, as well as publications about Ml.

• Supporting Tool Reuse with Model Transformation
• Unified Modeling Language Version 2.5

License

ml is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0), with portions covered by various BSD-like licenses.

See LICENSE-APACHE, and LICENSE-MIT for details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

ml's Issues

Use different generator library?

In order to get past the limits of the dot crate, perhaps it would make sense to use another graph generator, such as Jinja in Rust with a graphviz template similar to ansible-inventory-grapher's template.

using error_chain

I'm having issues with using error_chain for MML.

Cargo.toml

[package]
build = "build.rs"

[dependencies]
error-chain = "0.11.0"

[build-dependencies.mml]
version = "0.1"
error-chain = "0.11.0"

build.rs:

// UML Generator https://github.com/adjivas/ml

#![allow(unused_imports)]
#![allow(unused_variables)]
#![allow(dead_code)]

extern crate mml;

#[macro_use]
extern crate error_chain;

pub mod errors { error_chain!{} }

use errors::*;

fn make_uml_diagram() {
    // Generate diagram in /diagrams/ml.svg for README.md
    let dest: String = "../diagrams/".to_string();
    let _ = mml::src2both("src", dest.replace("-", "_").as_str());

    // Generate diagram in /target/doc/diamond_drops_node/ml.svg
    let dest: String = concat!("../target/doc/", env!("CARGO_PKG_NAME")).to_string();
    let _ = mml::src2both("src", dest.replace("-", "_").as_str());
}

fn main() {
    //make_uml_diagram();
}

$ cargo test
warning: unused manifest key: build-dependencies.mml.error-chain
   Compiling diamond-drops-node v0.1.0-a (file:///home/james/dod/node)
error[E0463]: can't find crate for `error_chain`
  --> build.rs:10:1
   |
10 | extern crate error_chain;
   | ^^^^^^^^^^^^^^^^^^^^^^^^^ can't find crate

error: aborting due to previous error

error E0423 in syntex_syntax

When I try using this on a few projects, I get a build error

error[E0423]: expected function, tuple struct or tuple variant, found struct `ast::Name`
   --> /home/jayvdb/.cargo/registry/src/github.com-1ecc6299db9ec823/syntex_syntax-0.58.1/src/symbol.rs:146:27
    |
146 |                       name: ast::Name($index),
    |                             ^^^^^^^^^
...
165 | / declare_keywords! {
166 | |     // Invalid identifier
167 | |     (0,  Invalid,        "")
168 | |
...   |
231 | |     (56, CrateRoot, "{{root}}")
232 | | }
    | |_- in this macro invocation
    |
    = note: this error originates in the macro `declare_keywords` (in Nightly builds, run with -Z macro-backtrace for more info)

e.g. I tried this with https://github.com/swift-nav/esthri/tree/master/crates/esthri
also some private projects which otherwise build normally.

Project state

Hello,

This project looks interesting; may I ask about the current state of the project in terms of maintenance and so on? If there is interest in maintaining this as a tool for generating UML from Rust crates and the goals are reasonably close to my own I would be interested in contributing. If on the other hand you know that e.g. some of the dependencies are unmaintained and this would be a huge amount of work then a clean slate approach might be better.

Best wishes, Max

Color graph elements

Coloring the svg graph output could make it more readable, like in this class diagram.

Link elements to documentation pages

When generating an svg image as part of a handbook, it would be really nice to deep link into the handbook from the source code diagram elements.

Example diagrams

We currently have one example diagram. In order to test the project and make it useful, other code bases can be diagrammed and linked here. This list shows what it can do:

• Development Utilities
  [-] ML -Modeling Language- (this project)

New folder structure

Hi,

the mml is not able to parse the newer folder structure, so I have to change it from:

"
folder [utility]
* one.rs
* two.rs
utility.rs
main.rs
"
to

"
folder [utility]
* one.rs
* two.rs
* mod.rs
main.rs
"

Infer component groupings based on folder structure

Would it be possible to organize the graph output structure like this visual paradigm - class diagram using the relationships encoded as a source code folder hierarchy? For example, this project's code seems organized well to fit that type of output.