[stdlib] add type_name module for type reflection

sblackshear · sblackshear · commit b1f887fa6ea9 · 2022-10-10T08:48:05.000-07:00
Move allows type-safe implementations of key types like fungible tokens using the Coin&lt;T&gt; standard. However, distinguishing coins at the type level only is sometimes limiting--e.g., you might want to write a DEX that has at most one pool for a given pair of currencies (need to compare types + reify the result in a value) or write a lending protocol that supports an extensible pool of currencies (need to reify the currency types + map them to the reserve coin supply).

This PR seeks to add the weakest form of reflection that supports use-cases like the ones above in order to keep static reasoning as simple/predictable as possible. Similar modules exist in the Starcoin and Aptos frameworks, and Sui users have also been requesting this feature.

- Add opaque `TypeName` value that can be produced from a Move type via `get&lt;T&gt;(): TypeName`
- Add functions for converting a `TypeName`'s into its inner representation as an ASCII strings so it can be compared or inspected. This is safe because the Move binary format enforces ASCII encoding for all identifiers

One issue worth discussing is whether we want to use the full-length representation of addresses (e.g., always produce a 16, 20, or 32 byte string, depending on the platform address length) or the "short" representation which strips leading 0's (e.g., the convention `0x1` for the Move stdlib). I think the former is slightly cleaner/more predictable, but I went with the latter because it already seems to be the standard in the `TypeTag` implementation of `Display`, as well as in the Aptos/Starcoin `TypeInfo` module that provides similar functionality to this code.
diff --git a/language/move-stdlib/docs/overview.md b/language/move-stdlib/docs/overview.md
@@ -21,6 +21,7 @@ This is the root document for the Move stdlib module documentation. The Move std
 -  [`0x1::option`](option.md#0x1_option)
 -  [`0x1::signer`](signer.md#0x1_signer)
 -  [`0x1::string`](string.md#0x1_string)
+-  [`0x1::type_name`](type_name.md#0x1_type_name)
 -  [`0x1::vector`](vector.md#0x1_vector)
 
 
diff --git a/language/move-stdlib/docs/type_name.md b/language/move-stdlib/docs/type_name.md
@@ -0,0 +1,128 @@
+
+<a name="0x1_type_name"></a>
+
+# Module `0x1::type_name`
+
+Functionality for converting Move types into values. Use with care!
+
+
+-  [Struct `TypeName`](#0x1_type_name_TypeName)
+-  [Function `get`](#0x1_type_name_get)
+-  [Function `borrow_string`](#0x1_type_name_borrow_string)
+-  [Function `into_string`](#0x1_type_name_into_string)
+
+
+<pre><code><b>use</b> <a href="ascii.md#0x1_ascii">0x1::ascii</a>;
+</code></pre>
+
+
+
+<a name="0x1_type_name_TypeName"></a>
+
+## Struct `TypeName`
+
+
+
+<pre><code><b>struct</b> <a href="type_name.md#0x1_type_name_TypeName">TypeName</a> <b>has</b> <b>copy</b>, drop, store
+</code></pre>
+
+
+
+<details>
+<summary>Fields</summary>
+
+
+<dl>
+<dt>
+<code>name: <a href="ascii.md#0x1_ascii_String">ascii::String</a></code>
+</dt>
+<dd>
+ String representation of the type. All types are represented
+ using their source syntax:
+ "u8", "u64", "u128", "bool", "address", "vector", "signer" for ground types.
+ Struct types are represented as fully qualified, <code>0x</code>-prefixed short type names
+ <code><a href="string.md#0x1_string_String">0x1::string::String</a></code> or
+ <code>0xabcd::module_name1::type_name1&lt;0x1234::module_name2::type_name2&lt;u64&gt;&gt;</code>
+ Note: addresses in short type names are *always* shortened by stripping leading 0's
+ e.g., 0xA rather than 0x00000000A,
+</dd>
+</dl>
+
+
+</details>
+
+<a name="0x1_type_name_get"></a>
+
+## Function `get`
+
+Return a value representation of the type <code>T</code>.
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_get">get</a>&lt;T&gt;(): <a href="type_name.md#0x1_type_name_TypeName">type_name::TypeName</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>native</b> <b>fun</b> <a href="type_name.md#0x1_type_name_get">get</a>&lt;T&gt;(): <a href="type_name.md#0x1_type_name_TypeName">TypeName</a>;
+</code></pre>
+
+
+
+</details>
+
+<a name="0x1_type_name_borrow_string"></a>
+
+## Function `borrow_string`
+
+Get the String representation of <code>self</code>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_borrow_string">borrow_string</a>(self: &<a href="type_name.md#0x1_type_name_TypeName">type_name::TypeName</a>): &<a href="ascii.md#0x1_ascii_String">ascii::String</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_borrow_string">borrow_string</a>(self: &<a href="type_name.md#0x1_type_name_TypeName">TypeName</a>): &String {
+    &self.name
+}
+</code></pre>
+
+
+
+</details>
+
+<a name="0x1_type_name_into_string"></a>
+
+## Function `into_string`
+
+Convert <code>self</code> into its inner String
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_into_string">into_string</a>(self: <a href="type_name.md#0x1_type_name_TypeName">type_name::TypeName</a>): <a href="ascii.md#0x1_ascii_String">ascii::String</a>
+</code></pre>
+
+
+
+<details>
+<summary>Implementation</summary>
+
+
+<pre><code><b>public</b> <b>fun</b> <a href="type_name.md#0x1_type_name_into_string">into_string</a>(self: <a href="type_name.md#0x1_type_name_TypeName">TypeName</a>): String {
+    self.name
+}
+</code></pre>
+
+
+
+</details>
+
+
+[//]: # ("File containing references which can be used from documentation")
diff --git a/language/move-stdlib/sources/type_name.move b/language/move-stdlib/sources/type_name.move
@@ -0,0 +1,29 @@
+/// Functionality for converting Move types into values. Use with care!
+module std::type_name {
+    use std::ascii::String;
+
+    struct TypeName has copy, drop, store {
+    	/// String representation of the type. All types are represented
+    	/// using their source syntax:
+    	/// "u8", "u64", "u128", "bool", "address", "vector", "signer" for ground types.
+        /// Struct types are represented as fully qualified, `0x`-prefixed short type names
+    	/// `0x1::string::String` or
+    	/// `0xabcd::module_name1::type_name1<0x1234::module_name2::type_name2<u64>>`
+    	/// Note: addresses in short type names are *always* shortened by stripping leading 0's
+        /// e.g., 0xA rather than 0x00000000A,
+        name: String
+    }
+
+    /// Return a value representation of the type `T`.
+    public native fun get<T>(): TypeName;
+
+    /// Get the String representation of `self`
+    public fun borrow_string(self: &TypeName): &String {
+        &self.name
+    }
+
+    /// Convert `self` into its inner String
+    public fun into_string(self: TypeName): String {
+        self.name
+    }
+}
diff --git a/language/move-stdlib/src/natives/mod.rs b/language/move-stdlib/src/natives/mod.rs
@@ -8,6 +8,7 @@ pub mod event;
 pub mod hash;
 pub mod signer;
 pub mod string;
+pub mod type_name;
 #[cfg(feature = "testing")]
 pub mod unit_test;
 pub mod vector;
@@ -23,6 +24,7 @@ pub struct GasParameters {
     pub hash: hash::GasParameters,
     pub signer: signer::GasParameters,
     pub string: string::GasParameters,
+    pub type_name: type_name::GasParameters,
     pub vector: vector::GasParameters,
 
     #[cfg(feature = "testing")]
@@ -52,6 +54,12 @@ impl GasParameters {
                     legacy_min_input_len: 0.into(),
                 },
             },
+            type_name: type_name::GasParameters { 
+                get: type_name::GetGasParameters {
+                    base: 0.into(),
+                    per_byte: 0.into(),
+                }
+            },
             signer: signer::GasParameters {
                 borrow_address: signer::BorrowAddressGasParameters { base: 0.into() },
             },
@@ -112,6 +120,7 @@ pub fn all_natives(
     add_natives!("hash", hash::make_all(gas_params.hash));
     add_natives!("signer", signer::make_all(gas_params.signer));
     add_natives!("string", string::make_all(gas_params.string));
+    add_natives!("type_name", type_name::make_all(gas_params.type_name));
     add_natives!("vector", vector::make_all(gas_params.vector));
     #[cfg(feature = "testing")]
     {
diff --git a/language/move-stdlib/src/natives/type_name.rs b/language/move-stdlib/src/natives/type_name.rs
@@ -0,0 +1,67 @@
+// Copyright (c) The Move Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+use move_binary_format::errors::PartialVMResult;
+use move_core_types::{
+    gas_algebra::{InternalGas, InternalGasPerByte, NumBytes},
+};
+use move_vm_runtime::native_functions::{NativeContext, NativeFunction};
+use move_vm_types::{
+    loaded_data::runtime_types::Type,
+    natives::function::NativeResult,
+    values::{Struct, Value},
+};
+
+use smallvec::{smallvec};
+use std::{collections::VecDeque, sync::Arc};
+
+
+#[derive(Debug, Clone)]
+pub struct GetGasParameters {
+    pub base: InternalGas,
+    pub per_byte: InternalGasPerByte,
+}
+
+// Adapted froom
+fn native_get(
+    gas_params: &GetGasParameters,
+    context: &mut NativeContext,
+    ty_args: Vec<Type>,
+    arguments: VecDeque<Value>,
+) -> PartialVMResult<NativeResult> {
+    debug_assert_eq!(ty_args.len(), 1);
+    debug_assert!(arguments.is_empty());
+
+    let type_tag = context.type_to_type_tag(&ty_args[0])?;
+    let type_name = type_tag.to_string();
+    // make a std::string::String
+    let string_val = Value::struct_(Struct::pack(vec![Value::vector_u8(
+        type_name.as_bytes().to_vec())]));
+    // make a std::type_name::TypeName
+    let type_name_val = Value::struct_(Struct::pack(vec![string_val]));
+
+    let cost = gas_params.base + gas_params.per_byte * NumBytes::new(type_name.len() as u64);
+
+    Ok(NativeResult::ok(
+        cost,
+        smallvec![type_name_val],
+    ))
+}
+
+pub fn make_native_get(gas_params: GetGasParameters) -> NativeFunction {
+    Arc::new(move |context, ty_args, args| native_get(&gas_params, context, ty_args, args))
+}
+
+#[derive(Debug, Clone)]
+pub struct GasParameters {
+    pub get: GetGasParameters
+}
+
+pub fn make_all(gas_params: GasParameters) -> impl Iterator<Item = (String, NativeFunction)> {
+    let natives = [
+        ("get", make_native_get(gas_params.get)),
+    ];
+
+    crate::natives::helpers::make_module_natives(natives)
+}
+
diff --git a/language/move-stdlib/tests/type_name_tests.move b/language/move-stdlib/tests/type_name_tests.move
@@ -0,0 +1,36 @@
+module std::type_name_tests {
+    #[test_only]
+    use std::type_name::{get, into_string};
+    #[test_only]
+    use std::ascii::string;
+
+    struct TestStruct {}
+
+    struct TestGenerics<phantom T> { }
+
+    #[test]
+    fun test_ground_types() {
+        assert!(into_string(get<u8>()) == string(b"u8"), 0);
+        assert!(into_string(get<u64>()) == string(b"u64"), 0);
+        assert!(into_string(get<u128>()) == string(b"u128"), 0);
+        assert!(into_string(get<address>()) == string(b"address"), 0);
+        assert!(into_string(get<signer>()) == string(b"signer"), 0);
+        assert!(into_string(get<vector<u8>>()) == string(b"vector<u8>"), 0)
+    }
+
+    #[test]
+    fun test_structs() {
+        assert!(into_string(get<TestStruct>()) == string(b"0x1::type_name_tests::TestStruct"), 0);
+        assert!(into_string(get<std::ascii::String>()) == string(b"0x1::ascii::String"), 0);
+        assert!(into_string(get<std::option::Option<u64>>()) == string(b"0x1::option::Option<u64>"), 0);
+        assert!(into_string(get<std::string::String>()) == string(b"0x1::string::String"), 0);
+    }
+
+    #[test]
+    fun test_generics() {
+        assert!(into_string(get<TestGenerics<bool>>()) == string(b"0x1::type_name_tests::TestGenerics<bool>"), 0);
+        assert!(into_string(get<vector<TestGenerics<u64>>>()) == string(b"vector<0x1::type_name_tests::TestGenerics<u64>>"), 0);
+        assert!(into_string(get<std::option::Option<TestGenerics<u8>>>()) == string(b"0x1::option::Option<0x1::type_name_tests::TestGenerics<u8>>"), 0);
+    }
+
+}
