Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/trunk' into series/M3
Browse files Browse the repository at this point in the history
  • Loading branch information
Arya Irani committed Mar 8, 2022
2 parents 0272143 + 4ff55dc commit 2224cbc
Show file tree
Hide file tree
Showing 9 changed files with 21 additions and 21 deletions.
2 changes: 1 addition & 1 deletion development.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ These are commands that will likely be useful during development.

__General:__ `./scripts/test.sh` compiles and builds the Haskell code and runs all tests. Recommended that you run this before pushing any code to a branch that others might be working on.

_Disclaimer_ If you have trouble getting started, please get in touch via [Slack](https://unisonweb.org/community) so we can help. If you have any fixes to the process, please send us a PR!
_Disclaimer_ If you have trouble getting started, please get in touch via [Slack](https://unison-lang.org/community) so we can help. If you have any fixes to the process, please send us a PR!

## Running Unison

Expand Down
16 changes: 8 additions & 8 deletions docs/type-declarations.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ data DataDeclaration' v a = DataDeclaration {
## Structural Types

> 👉 These got implemented - it's the default, so there's no `structural` keyword.
> 👉 These got implemented - it's the default, so there's no `structural` keyword.
Structural types are defined uniquely by their structure. Every constructor has a unique signature, which intrinsically defines the meaning of the constructor. For example, the following types are identical and interoperable:

Expand All @@ -40,7 +40,7 @@ The identity of a structural type is determined by normalizing the constructor o

## Unique types

> 👉 This got implemented - see [here](http://unisonweb.org/docsite/languagereference.html#unique-types).
> 👉 This got implemented - see [here](https://www.unison-lang.org/learn/language-reference/unique-types/).
Unique types have extrinsic semantics, not completely defined by the constructor types. Their representation includes a GUID, along with the constructors. The constructors types need not be unique. The GUID is typically auto-generated, but can be specified as part of the type declaration, in order to use a textual representation to declare an identical type.

Expand All @@ -55,9 +55,9 @@ Order of constructors having the same type is stable, but the relative construct

## Opaque Types

How do we support modularity? That is, how do we let people expose a 'public API' to their library, and avoid exposing the internals behind it, so that (a) you can keep your library's internal data invariants intact without having to explain them, (b) you're free to change the internals without breaking client code that uses the API, and (c) you can tame complexity in the overall system by decoupling client code from library code?
How do we support modularity? That is, how do we let people expose a 'public API' to their library, and avoid exposing the internals behind it, so that (a) you can keep your library's internal data invariants intact without having to explain them, (b) you're free to change the internals without breaking client code that uses the API, and (c) you can tame complexity in the overall system by decoupling client code from library code?

The key thing is to control access to the introduction and elimination of data types: who is allowed to create, and to pattern-match on, a value of your type? Both of those necessarily expose the guts of the representation of the type.
The key thing is to control access to the introduction and elimination of data types: who is allowed to create, and to pattern-match on, a value of your type? Both of those necessarily expose the guts of the representation of the type.

An opaque type has a structure and a block of terms that can inspect structure. The hash of those terms is part of the type ID. They have a flag in the decl so typechecker can prevent access.

Expand All @@ -76,7 +76,7 @@ Notes re Scala opaque types:

### Alternative take on opaque types

The thread starting [here](https://unisonlanguage.slack.com/archives/CLKV43YE4/p1565135564409000) makes the case that it's not very 'open world' to force people to change your type's identity in order to add a function which is privileged - i.e. can create and pattern match on values of that type.
The thread starting [here](https://unisonlanguage.slack.com/archives/CLKV43YE4/p1565135564409000) makes the case that it's not very 'open world' to force people to change your type's identity in order to add a function which is privileged - i.e. can create and pattern match on values of that type.

An alternative would be to say that, in terms of type identity, opaque types work exactly like unique types. But that you can annotate terms as being a 'friend' of that type, and so allowed to create / pattern match. So maybe here's what a term looks like that's a friend of types Foo and Bar:

Expand All @@ -90,15 +90,15 @@ This annotation would be metadata attached to the term. You can get unison to l

### Private functions

It's not quite true to say that controlling creation and pattern matching is enough for the three aspects of modularity mentioned above. What about internal library helper functions which could be called in a way that creates data that doesn't respect the invariants? Or that you might want to change or remove later? Or that are not at the same semantic level as your API? So maybe we'd want a `private[Foo]` annotation on terms, which both implies `friend[Foo]`, and can only be referenced from other `friend[Foo]` terms.
It's not quite true to say that controlling creation and pattern matching is enough for the three aspects of modularity mentioned above. What about internal library helper functions which could be called in a way that creates data that doesn't respect the invariants? Or that you might want to change or remove later? Or that are not at the same semantic level as your API? So maybe we'd want a `private[Foo]` annotation on terms, which both implies `friend[Foo]`, and can only be referenced from other `friend[Foo]` terms.

## Combinations?

_Structural + Unique:_ No.

_Structural + Opaque:_ No.

_Unique + Opaque:_ Sure why not.
_Unique + Opaque:_ Sure why not.

(So note that Opaque implies Unique.)

Expand Down Expand Up @@ -129,7 +129,7 @@ data IsOptional
| OnePlus -- 1 or more, at the end
deriving Show
```
I still want this to be the same type. None of the semantics have changed, I just reordered the constructors for readability. I don't think this would be possible with any of our current proposed type implementations. Yes, I could create a new unique type, and refactor everything to use that, but that strikes me as unappealing, especially from a code-sharing perspective.
I still want this to be the same type. None of the semantics have changed, I just reordered the constructors for readability. I don't think this would be possible with any of our current proposed type implementations. Yes, I could create a new unique type, and refactor everything to use that, but that strikes me as unappealing, especially from a code-sharing perspective.

Thoughts?

Expand Down
2 changes: 1 addition & 1 deletion parser-typechecker/src/Unison/PrintError.hs
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ defaultWidth = 60

-- Various links used in error messages, collected here for a quick overview
structuralVsUniqueDocsLink :: IsString a => Pretty a
structuralVsUniqueDocsLink = "https://www.unisonweb.org/docs/language-reference/#unique-types"
structuralVsUniqueDocsLink = "https://www.unison-lang.org/learn/language-reference/unique-types/"

fromOverHere' ::
Ord a =>
Expand Down
8 changes: 4 additions & 4 deletions parser-typechecker/src/Unison/Runtime/IOSource.hs
Original file line number Diff line number Diff line change
Expand Up @@ -538,12 +538,12 @@ metadata.isPropagated = IsPropagated.IsPropagated
-- A newtype used when embedding term references in a Doc2
unique[fb488e55e66e2492c2946388e4e846450701db04] type Doc2.Term = Term Any

-- Media types for Doc2.Embed.
-- Media types for Doc2.Embed.
-- Somewhat modelled after:
-- https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source and
-- https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video

unique[ab9344724264495159ec7122d276a6358630403b6a5529e1e5d76bcf] type Doc2.MediaSource
unique[ab9344724264495159ec7122d276a6358630403b6a5529e1e5d76bcf] type Doc2.MediaSource
= { sourceUrl: Text, mimeType: Optional Text }

-- Used with MediaSource to embed videos in a Doc. The `config` field is
Expand All @@ -555,7 +555,7 @@ unique[b2ada5dfd4112ca3a7ba0a6483ce3d82811400c56eff8e6eca1b3fbf] type Doc2.Video
}

-- Useful for embedded data into a Doc, like title, date, tags etc:
unique[ea60b6205a6b25449a8784de87c113833bacbcdfe32829c7a76985d5] type Doc2.FrontMatter
unique[ea60b6205a6b25449a8784de87c113833bacbcdfe32829c7a76985d5] type Doc2.FrontMatter
= FrontMatter [(Text, Text)]

-- ex: Doc2.term 'List.map
Expand Down Expand Up @@ -636,7 +636,7 @@ unique[b7a4fb87e34569319591130bf3ec6e24c9955b6a] type Doc2
| NumberedList Nat [Doc2]
-- Section title subelements
| Section Doc2 [Doc2]
-- [our website](https://unisonweb.org) or [blah]({type MyType})
-- [our website](https://www.unison-lang.org/) or [blah]({type MyType})
| NamedLink Doc2 Doc2
-- image alt-text link caption
| Image Doc2 Doc2 (Optional Doc2)
Expand Down
4 changes: 2 additions & 2 deletions unison-cli/src/Unison/CommandLine/Welcome.hs
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ authorSuggestion =
[ P.wrap "📜 🪶 You might want to set up your author information next.",
P.wrap "Type" <> P.hiBlue " create.author" <> " to create an author for this codebase",
P.group (P.newline <> P.wrap "Read about how to link your author to your code at"),
P.wrap $ P.blue "https://www.unisonweb.org/docs/configuration/#setting-default-metadata-like-license-and-author"
P.wrap $ P.blue "https://www.unison-lang.org/learn/tooling/configuration/"
]

getStarted :: FilePath -> IO (P.Pretty P.ColorText)
Expand All @@ -172,7 +172,7 @@ getStarted dir = do
P.column2
[ ("📖", "Type " <> P.hiBlue "help" <> " to list all commands, or " <> P.hiBlue "help <cmd>" <> " to view help for one command"),
("🎨", "Type " <> P.hiBlue "ui" <> " to open the Codebase UI in your default browser"),
("📚", "Read the official docs at " <> P.blue "https://unisonweb.org/docs"),
("📚", "Read the official docs at " <> P.blue "https://www.unison-lang.org/learn/"),
(earth, "Visit Unison Share at " <> P.blue "https://share.unison-lang.org" <> " to discover libraries"),
("👀", "I'm watching for changes to " <> P.bold ".u" <> " files under " <> (P.group . P.blue $ P.string dir))
]
Expand Down
2 changes: 1 addition & 1 deletion unison-src/transcripts-using-base/fix2297.output.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,6 @@ wat = handleTrivial testAction -- Somehow this completely forgets about Excepti
Learn more about when to use `structural` vs `unique` in the
Unison Docs:
https://www.unisonweb.org/docs/language-reference/#unique-types
https://www.unison-lang.org/learn/language-reference/unique-types/
```
2 changes: 1 addition & 1 deletion unison-src/transcripts/fix1696.output.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,6 @@ dialog = Ask.provide 'zoot '("Awesome number: " ++ Nat.toText Ask.ask ++ "!")
Learn more about when to use `structural` vs `unique` in the
Unison Docs:
https://www.unisonweb.org/docs/language-reference/#unique-types
https://www.unison-lang.org/learn/language-reference/unique-types/
```
4 changes: 2 additions & 2 deletions unison-src/transcripts/type-modifier-required.output.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ type Abc = Abc
Learn more about when to use `structural` vs `unique` in the
Unison Docs:
https://www.unisonweb.org/docs/language-reference/#unique-types
https://www.unison-lang.org/learn/language-reference/unique-types/
```
Abilities needs to be prefixed with either `unique` or `structural`:
Expand All @@ -33,7 +33,7 @@ ability MyAbility where const : a
Learn more about when to use `structural` vs `unique` in the
Unison Docs:
https://www.unisonweb.org/docs/language-reference/#unique-types
https://www.unison-lang.org/learn/language-reference/unique-types/
```
There should be no errors when `unique` or `structural` is provided:
Expand Down
2 changes: 1 addition & 1 deletion yaks/easytest/easytest.cabal
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ license-file: LICENSE
author: Paul Chiusano
maintainer: Paul Chiusano <[email protected]>
stability: provisional
homepage: http://unisonweb.org
homepage: http://unison-lang.org
bug-reports: https://github.com/unisonweb/unison/issues
copyright: Copyright (C) 2016 Paul Chiusano and contributors
synopsis: Simple, expressive testing library
Expand Down

0 comments on commit 2224cbc

Please sign in to comment.